MULTICS MENU 

CREATION 

FACILITIES 



MULTICS MENU CREATION FACILITIES 



SUBJECT 

Description of the Multics Menu Creation Facilities 

SPECIAL INSTRUCTIONS 

This publication superesedes the previous edition of the manual. Order No. CP51-01, 
dated July 1982, and its addenda CF51-01A, dated August 1982, CP51-01B, dated 
February 1983, and CP51-01C, dated December 1983. 

Throughout the document change bars are used to indicate technical changes and 
additions; asterisks denote deletions. 

Refer to the Preface for "Significant Changes." 

SOFTWARE SUPPORTED 

Multics Software Release 11.0 

ORDER NUMBER 
CP51-02 

DATE 

February 1985 



PREFACE 



The publication is intended for application programmers who are building menu 
interfaces to existing software. The Multics menu system consists of several commands and 
subroutines which can be used to create and manage menus. 



The major topics presented are: 

• A description of the terminal-management software that provides a means of dividing 
the terminal screen into different regions and of performing real-time editing. The 
terminal-management software is referred to in text as the "video system." 

• A description of the Multics commands and subroutines provided for creation and 
manipulation of video screens and creation and display of menus. 

• A description of the Multics I/O modules that support terminal-management functions. 



There are some manuals that are prerequisites to this one in that they describe tools 
that the application writer uses. The writer must be familiar with Multics I/O processing, 
commands, and subroutines. The manuals describing these are as follows: 

Multics Programmer's Reference Manual Programmer's Reference 

(Order No. AG91) 



Multics Commands and Active Functions Commands 
(Order No. AG92) 

Multics Subroutines and I/O Modules Subroutines 
(Order No. AG93) 



The information and specifications in this document are subject to change without notice. This 
document contains information about Honeywell products or services that may not be available 
outside the United States. Consult your Honeywell Marketing Representative. 



© Honeywell Information Systems Inc., 1985 



File No.: 1L13, 1U13 CP51-02 



The Programmer's Reference manual describes I/O processing and contains specific 
details for the use of screen terminals. The Ckimmands manual contains the descriptions of 
commands that are referenced in text, such as exec_com. The Subroutine manual contains 
Multics subroutine descriptions. 



In addition, this publication assumes the programmer is familiar with PL/I, FORTRAN, 
or COBOL, and tiie Multics exec_com facility. (The €xec_com examples in this document use 
Version 2 of exec_com.) The PL/I language is described in the PLII Language Specification, 
(Order No. AG94); the FORTRAN Language is described in the FORTRAN Reference 
l\Aanual, Order No. AT58); the COBOL Language is described in the COBOL Reference 
Manual, (Order No. AS44). 



Significant Changes in CP51-02 

The video system now supports windows which do not extend across the full width of 
the screen. See Section 2 for details. 



The video system editor now accepts either upper or lower case letters when you use 
default escape sequences. See Section 4 for details. 



The "suppress_redisplay" field has been added to the line_editor_info structure. See 
Section 4 for details. 



The "window_caH" command now accepts the "-width NC (-wid NC)" control argument 
which specifies the width of . a r^on for a request See the "window_caH" command in 
Section 5. 



The "change_window" and "create_window" arguments to the "window.call" command 
now accept the "-column C and "-width NC control argument. See Section 5. 



A "-line_speed (-Is)" control argument has been added to "window_call invoke". This 
allows you to specify the speed of your connection to Multics when you use the video 
system. If no "-line_speed" is specified, the current iine_speed is used. See Section 5 for 
details. 



The "window_$edit_line" entry which allows applications to preload the video editor 
input buffer with a string, has been added to the window, subroutine. See Section 6 for 
details. 



The "window_$write_raw_text" entry in the window_ subroutine now causes the cursor 
position to become undefined and sets the screen_in valid window status flag. See Section 6. 
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Support for the "set_term_type" control order has been added to the tc_io_ I/O 
module. This control order or the set.tty command allows you to change the terminal type 
in a video session. 



Two new control arguments have been added to window_io_ switch. The "-first_column 
COL_NO" (control argument) is the column number on the screen where the window is to 
begin. The "-width N CDLS" (control argument) is the number of columns in the window. 
See Section 7. 



The "set_output_conversion" and "get_output_conversion" control orders have been added 
to the window_io_ I/O module. The "get_output_con version" control order obtains the 
current contents of the specified table. The "set_output_conversion" control order provides a 
table to use in formatting output to identify certain kinds of special characters. See Section 7 
for details. 



The "get_special" and "set.special" control orders have also been added to window_io_. 
The "get_special" control order obtains the contents of the special_chars table currently in 
use. The "set_speciar' control order provides a table that specifies sequences to be substituted 
for certain output characters. See Section 7. 



A "get_editor_key_bindings" control order, which returns a pointer to the 
line_editor_key_binding structure describing the key bindings, has been added to window_io_. 
The "set_editor_key_bindings" control order has been changed. New fields have been added to 
the line_editor_key_binding structure. The control arguments "-name STR", "-description 
STR", and "-info_pathname PATH" have been added to the io_call support set_editor_key_bindings 
1 control order. 



A new mode, "edited, '^edited" suppresses printing of characters for which there is not 
defined Multics equivalent on the device referenced. See Section 7 for details. 
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SECTION 1 



INTRODUCTION TO THE MENU SYSTEM 



Multics is a large-scale, interactive system with a rich repertoire of commands, 
subroutines, tools and many interrelated subsystems. There are over 2,000 commands and 
subroutines alone. Effective use of the power this system has to offer is a specialty not 
every user masters. In many cases there is no reason to master it The majority of users 
have specific tasks to accomplish online and require only a small subset of the available tools. 
What they do need to know is what tools exist to get their job done most efficiently. The 
easier it is to figure that out, the better. Since many of these people are not trained in 
computer use, the system should be made easy to understand, provide flexibility and keep 
training at a minimum. The Multics menu system provides a means of accomplishing this. 



WHAT IS A MENU 

A menu is a list of options presented to the user on a video terminal. By typing a 
single key, designating an option choice, an action is performed. The most important feature 
the menu system has to offer is permitting the user who knows very little about the system 
to interact with the computer. No knowledge of commands is required since the system calls 
the command to do the job once the user indicates an option. All the actions required for a 
specific task are displayed on the tenninal, selections are made, and the user is ushered 
through a given task by being prompted. You can design menus for all different levels of 
expertise and for any number of tasks. The easiest way to explain the menu system and to 
provide application ideas is to give examples of menus. The menu "Games" is shown here. 



Type a number and the corresponding action will be performed. 




6) Play Star Trek 

7) Play Adventure 



3) Play Football 
k) Play Basebal 1 



8) Guess the Animal 

9) Play Backgammon 



3) Do a Simulated Parachute Jump 
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Imagine that the boxes in all the examples in this section are on terminal screens. This 

entire display is defined by the menu application. The screen is divided into two sections 
with the top part of the screen for menu display and the bottom part of the screen for user 
input/output 



The user of this menu selects one of the options and the screen changes from the list 
of menu options to the description of a specific game. The screen is no longer divided into 
two parts and the user input/ output section of the screen is expanded to full size. For 
example, if Option 5 is selected, the transactions appear as follows. In this example, 
user-typed input is preceded by an exclamation point 



Welcome to "splat" — the game that simulates a parachute jump. 
Try to open your chute at the last possible moment without 
going splat. 

Select your own altitude? !yes 
What altitude (ft)? !5000 



When the user is finished playing this game, the screen goes back to the original menu 
display. Another option is selected or the user exits this particular menu. 



The next example is a menu for Tess True-Heart, a new terminal operator. Other than 
knowing how to login, Tess is a Multics novice. She needs to learn a little bit about the 
Multics system, i.e., how a command works, how to read her mail, and what manuals to read 
for details. Tess is at an advantage because the word processing system she worked on in her 
previous job also used menus, so she understands the concept This is an important advantage 
for the application writer too. Since menus are used widely throughout the industry, people 
who use your menus will not find the concept a foreign one. As illustrated below, the menu 
system quite effectively "fences off" the Multics system into an understandable set of tools 
for personal use. The following example was written for Tess as an introduction to Multics. 
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«<MULTICS TUTORIAL»> 

1) What is a command? 

2) What commands do i use everyday? 

3) What commands are helpful but not essential? 
k) How do I read and send mail? 

5) What manuals are helpful for a beginner? 

6) Where do I go from here? 



As an example of the material in some of these options. Option 2 might discuss the 
list, help, and dprint commands. All the commands Tess is likely to use in her daily work 
are candidates for this option. 



The commands in Option 3 would be more sophisticated and might include exec_com 
and the absentee commands. 



Another example of a menu user is Percival C. Monday. Percy has no former 
experience with a computer and it is peripheral to his job. He uses it essentially as a filing 
system. This application is not unlike one intended for ticket agents at an airline counter, 
who use a computer strictly for one set of tasks. Percy must be able to read orders received, 
process orders, file the orders, check the budget allocation /expenditures, charge a department, 
maintain an inventory and change the inventory as orders are filled and shipments arrive. A 
menu to accomplish these tasks might look like this: 



«<MANUAL ORDERS»> 
Enter the number corresponding to the function to be performed. 

1) List orders to be processed 

2) List orders processed this month 

3) List budget information 
k) Enter billing information 
5) Update Inventory 
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In the previous examples, the user went from a menu to the game "parachute jump" or 
to explanations of commands. In this example, Percy is going from the first menu to other 
menus. If Percy selects Option 5, the screen mig^t look like this: 



1) List of parts available 

2) Additions made to inventory list 

3) Deletions made to inventory list 



Percy selects one of the options in this list and performs the appropriate action. 



The first three examples are for inexperienced users and the advantages for such persons 
are obvious. However, the menu system can be tailored for the experienced user as well. The 
next example is a manager's application. The manager is Gloria VanDerMint, who has five 
people working for her in the research and development department In addition to her 
development work, she has a number of tasks that must be performed routinely, so you can 
incorporate them all into one menu. You can set up a number of data bases containing 
information such as weekly status reports from her unit, and from these she writes the unit 
status report or performance appraisals, and updates schedules. You may also include the 
memo command to remind her when performance appraisals and status reports are due. 
Another convenient command to incorporate is calendar, which reminds her of meetings and 
trips. Gloria's menu is given below. 



«<The Good, The Bad, and The Boring»> 



1) Read memos 

2) Send memos 

3) Calendar 

h) Modify calendar 

5) Unit Status repo 



6) Personal Schedules 

7) Produce Schedules 

8) Performance Appraisal Form 



rts 
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An additional menu for more complex tasks is one that offers a choice of programming 
procedures. This is helpful for people who have programmed on other systems but not on 
Multics and discusses the languages and editors available, tells them about formatting programs 
explain compiling on Multics and discusses debugging tools. It might contain the following: 



THE CONNECTION BETWEEN THE MENU SYSTEM AND THE VIDEO SYSTEM 

In the next section, the video system is introduced. A more detailed discussion is 
presented in Section 4. Menu application programs use the video system to manage the 
display on the terminal screen. As noted above, all these example have the screen divided 
into portions which have different uses. Since we cannot physically divide the screen, we 
must do it logically. This is the job of the video system, and this terminal management is 
required to support the menu software. 



«<Programnii ng Procedures»> 



1) Name Your Language 

2) Enter New Program 

3) Update Existing Program 



h) Format Your Program 

5) Execute Your Program 

6) Debug Your Program 
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SECTION 2 

INTRODUCTION TO THE VIDEO SYSTEM 



The advent of comparatively low cost video terminals has brought a new dimension to 
the computing industry. Today's video terminals have many more capabilities than hard copy 
ones. Real-time editing, and higher speed communication are available and the display can 
change easily and quickly with varied functions. 



The video system is a terminal-independent presentation interface. This means that an 
application can run on any supported terminal and produce essentially the same display. The 
video system enables the application writer to divide the terminal screen into "windows" to 
partition the display. The menu writer must have a thorough understanding of windows; how 
to invoke the video system (the first step in the process of creating windows), how to revoke 
the video system, and how to create, destroy, change and clear windows. This section 
discusses design considerations involved in using windows and covers the video material most 
important to the menu application writer. For a more detailed description of the features of 
the video system, see Section 4 of this manual. 



WHAT IS A WINDOW 

A window is an area of the screen whose contents can be manipulated without affecting 
the rest of the display. For example, the user may scroll the contents of a segment in one 
window without moving the contents of the segment displayed on any other part of the 
screen. 



Each window behaves like an individual video terminal. Many possible operations may 
be performed on a window. These include displaying characters, moving the cursor, erasing 
lines, inserting lines, and others. Characters are normally sent to a window via the Multics 
I/O system and the iox_ subroutine (see the Multics 110 and Subroutines manual. Order | 
No. AG93). Additional operations specific to the capabilities of video terminals are | 
performed by the window_ subroutine (described in Section 6), which is analogous to iox_. 



A window is a rectangular region of the screen. The screen can be divided into several 
windows that can be viewed simultaneously but the windows may not overlap. The number of 
line and columns in each window can vary. A window can be one column wide or it can 
extend across the full width of the screen. 



The size of a window is specified at the time the window is created. Character 
positions are identified by line and column with the origin (or home) located at the upper 
left hand comer of the window. Each window has its own home, line 1, column 1, and 
character positions are always with respect to the home of the specific window. 
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If you want to create a window from command level, use the window_call command 
with the create_window argument You can also use the window_create entry to the window_ 
subroutine to create a window on the terminal screen. (Refer to the description of window_ 
subroutine later in this manual.) 

The conmiand syntax for creating windows from command level is: 

window__call create_wi ndow -io_switch WINDOW 
{-line L -column C -height NL -width NC} 

window_call, wdc 

this command provides a command interface to the video system 

create_window, crwd 

this argument creates a new window on the screen 

-io^switch WINDOW 1 -io_switch 

WINDOW 1 specifies the window associated with the given I/O switch. 

-line L 

specifies the line number on the screen where the window is to begin. To create a 
window beginning on the third line, use -line 3. If -line is not specified, the default is 
line 1. 

-column C, col C 

specifies the column number on the screen where the window is to begin. To create a 
window beginning in the third column, use -column 3. If -column is not specified, the 
default is column 1. 

1 height NL, -hgt NL 

specifies the height of the window. To create a window 10 lines high, use -height 10. If 
-height is not specified, the default is the remainder of the screen. 

-width NC, -wid NC 

specifies the width of the window. To create a window 20 columns wide, use -width 20. 
If -width is not specified, the default is the remainder of the screen. 



Figure 2-1 is an example of three different types of windows that you can create on a 
screen. You can create a window called WINDOW_l that is 20 columns wide and 10 lines 
high. This window begins on the third line and the second column. To create WIND0W_1 
(shown in Figure 2-1), type the following command line: 

wdc crwd -is WIND0W_1 -line 3 -column 2 -height 10 -width 20 



You can also create a second window on the same screen called WIND0W_2. This 
window is 3 columns wide and begins in colunm 25. Since line and height are not specified, 
the window begins in line one and fills the remainder of the screen. To create WIND0W_2 
(shown in Figure 2-1), type: 

wdc crwd -is WIND0W_2 -column 25 -width 3 
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You can create a third window on the screen called WIND0W_3. This window is 14 
columns wide and 7 lines high. This window begins at line 17 and column 32. To create 
WIND0W_3 (shown in Figure 2-1). type: 

wdc crwd -is WIND0W_3 -line 17 -column 32 -height 7 -width ^k 



Refer to Section 5 for more information on these commands and other commands used 
by the menu and video software. 



WINDOW 1 



H 



WIND0W_3 



Figure 2-1. Windows on a Screen 



Window Capabilities 

The capabilities defined for a window are grouped into five categories! positioning the 
cursor, selective erasure, scrolling, selective alteration, and miscellaneous. Window operations 
may be performed with the window_call command or by a call to the window_ subroutine. 
These are described in Sections 5 and 6 respectively. 
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POSITIONING THE CURSOR 



Each window has its own logical cursor. This cursor exists even when the terminal's 
cursor is performing operations in another window. The position of this cursor may be 
explicitly changed in a variety of ways. The cursor can be positioned absolutely or relatively. 
Absolute positioning can be to the home position or to an arbitrary line and column. 
Relative positioning can be up, down, left, or right any number of positions. The cursor also 
moves as characters are displayed in the window. 



SELECTIVE ERASURE 

Selective Erasure (or clearing) means changing some region of the display so that no 
visible characters appear in that region, without changing any other area of the window. Most 
video terminals are capable of at least some selective erase operations. Where possible, the 
video system uses any special terminal features present to clear regions. When the terminal 
has no useful feature for clearing the specified region, regions are cleared by overwriting 
them with spaces. This can be a rather slow operation. 



A region is a rectangle contained within a window. Like a window, it has an extent 
(height and width) and a position. All erasure operations pertain to regions. The definition of 
the region may be explicit (position and extent supplied in the call) or implicit (the region 
begins at the current cursor location, or at home). The cursor is always left at the origin of 
the region. 



A window may be cleared: entirely, from the home to the end of the window; from 
the current cursor position to the end of the current line in the window; from the current 
cursor position to the end of the window. An arbitrary region may also be cleared. 



SCROLLING 

A window may be scrolled up or down by a given number of lines. Scrolling up means 
moving lines up from the bottom of the window - deleting lines at the top, and adding new, 
blank lines at the bottom. Scrolling down means moving lines from the top of the window 
down, deleting at the bottom and adding at the top. Scrolling is usually done automatically 
by the video system when output fills the window, but it can also be requested explicitly. 



SELECTIVE ALTERATION 

Selective alteration means adding or deleting characters or lines in the middle of the 
window. When characters (or lines) are added, adjoining characters (or lines) move over to 
make room for the new ones. When characters (or lines) are deleted, characters (or lines) 
move in to fill up the gap. This differs from selective erasure, which only affects the 
characters erased. 



MISCELLANEOUS 

Among other things, entries are provided in the window_ subroutine and the 
window_call command to sound an audible alarm, to obtain the current cursor position, and 
to output an arbitrary character sequence. 
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Window/Video Commands and Subroutines 

The command supporting windows is introduced here but is explained in detail in 
Section 5 of this manual. 

window_call 

is the command interface to the video system. This is used in exec_com applications 
while the window_ subroutine is used in PL/ 1, ft_window_ is used in FORTRAN, and 
cb_window_ is used in COBOL applications. 



The subroutines supporting windows and the video system are described in detail in 
Section 6 of this manual and are as follows: 

video_utils_ 

activates and deactivates the video system. 

video_data_ 

is a data segment containing information about the video system. 
window_ 

is the subroutine interface to the video system. It is the corresponding subroutine to the 
window_call command. 



Attaching the Video System 

You must check whether or not the users of the proposed menu have the video system 
turned on. It is not likely that novice users would do this initially but it might be included 
in a project start_up. If it is on, it is important that you leave it alone. Do not turn it on 
again or you will get an error m^sage. If you have determined that the video system is 
turned on, you should then have your application use the space allocated to the 
user_input/ output window instead of the whole screen. Thus, if the user creates a separate 
window for interactive messages, an application should not use that space. Using the space 
allocated to the user_io window respects the user's explicit wishes and prevents violation of 
the restriction against using two overlapping windows at the same time. 



When the video system is invoked, the entire screen is covered by a window associated 
with the user_i/o I/O switch. Determine how much of the screen you have and divide up 
that amount for use by your application. Since terminals vary in the length of the screen, 
and some users already may have some lines devoted to their own video display, you are 
probably dealing with less than 20 lines, so design with that in mind. As long as there are 
eight or ten lines available for user input/output that should be sufficient 



The first step then is determining whether or not the video system is turned on and, if 
not, turn it on. This should be included at the beginning of all menu applications. The 
following is the exec_com example. The lines are numbered only for the purpose of 
explanation and should not be included in your exec_com. 
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1 &set al ready_video &[io attached user_terml nal_] 

2 Sif &[not & (al ready_video) ] 

3 &then window__can invoke 

k &set first_line &[wi ndow__cal 1 get_f i rst_l ine] n_lines 
& [w i ndow_ca 1 1 ge t__w i ndow__he i gh t] 

where: 

1. determines whether or not the video system is attached to the user's terminal. 

2. turns it on if it isn't already on. 

3. invokes window_call initiating the window environment 

4. sets the lines for the window. This is part of the first step because when you revoke 
the video system at the end of the exec_com, you must set the screen to the size it 
was originally. 

The following is the PL /I example that does the same thing. Declare statements are included 
in the example. Again, the lines are numbered for the purpose of explanation and the 
numbers should not be included in your program. 

del (addr, null) builtin; 

del iox_$control entry (ptr, char (*) , ptr, fixed bin (35)); 

del eom_err_ entry () options (variable); 

del iox_$user_!0 ptr ext static; 

del video__ut i 1 s__$turn__on_logi n__channel entry 

(fixed bin (35) , char (*) ) ; 

del video_data__$termi nal__ioeb ext static ptr; 

del ME char (32) init ("test_prograin") static options (constant); 

del code fixed bin (35); 

del al ready_video bit (1); 

del reason char (128) ; 

1 % include wi ndow_control_i nf o; 

2 del 1 my_wi ndow_i nf o like window_posi tion_info; 

3 my_wi ndow_i nfo. vers ion = wi ndow_pos i t i on_i nf o_vers i on_^l ; 
k if video_data^$terminal_iocb = null () then do; 

5 call video_uti ls_$turn_on_login__channel (code, reason); 

6 if code ^= 0 then do; 

call com__err__ (code, ME, '"^a", reason); 
return; 

end; 

7 al ready_video = "0"b; 
end; 

8 else al ready_video = "T'b; 

9 call iox_$control (iox__$user__i o, "get_wi ndow_i nf o", 

addr (my_wi ndow_i nfo) , code); 
10 if code ^= 0 then do; 

call com_err_ (code, ME, "get__wi ndow_i nf o") ; 
return; 
end; 
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where: 



1. includes appropriate structure declarations 

2. declares an automatic copy of window info 

3. sets the version number of window info 

4. determines if the video system is not activated then does 4 through 6 

5. turns on the video system and 

6. if there is an error, reports it to the caller and quits 

7. makes a note to the effect that video was invoked by this program 

8. goes to here if the video system is already activated (video was not activated by this 

program) 

9. gets the current size and location (beginning line number) of the user_i/o window 
10. prints error message 



Detaching the Video System 

At the end of the exec_com, you have to turn off video and leave things as you found 
them. First, is the exec_com example for revoking the video system. The lines are numbered 
only for the purpose of explanation and these numbers should not be included in your 
exec_com. 

1 6if & (al ready_vi dec) 

2 6 then window_call change_wi ndow -line & (f i rst__l i ne) 

-hei ght & (n_l i nes) 

3 Seise window_call revoke 

where: 

1. determines whether or not video was activated by this exec_com. 

2. if video was activated by another exec_com, then user_i/o window is returned to 
previous size and it is cleared. 

3. otherwise, the window interface to the video system is deactivated and the user_i/o 
window goes to full screen. 

The PL/I example: 

1 if al ready_video then do; 

2 call video_ut i 1 s_$turn__of f_logi n_channel (code) ; 

if code ^^=0 then do; 



end; 
end; 

3 else do; call iox_$contro1 (lox_$user_io, "set_window_info", 

addr (Miy_w : ridow_i nf c) , code) ; 
if code ^^=0 then do; 



end; 
end; 
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where: 



1. determines whether or not video was activated by this program. 

2. if video was previously attached, then the user_i/o window is returned to its previous 
size. 

3. if the video system was activated by this program, it is then deactivated and the 
user_i/o window goes to full screen. 



Design Requirements for Windows 

In Section 1, all of the examples used two windows: the top window which displayed 
the menu itself and the bottom window which was for user input/output. As part of the 
menu design process, you decide ahead of time how the display will look and from that 
determine the number of windows that will be advantageous. 



As an example, you may have the screen divided into three windows. The top window 
could display the status of the user with the user name, a description of what he's doing and 
a clock. The middle window could contain various menus and could grow or shrink 
depending on the selection made. The bottom window could be for unformatted- output and 
for typing in input 



The number of windows technically permitted is quite large and probably more than you 
will need. Knowing how many functions are to be performed, you should carefully select the 
number of windows to be used by an application. It is possible on a 24 line terminal to 
have 24 windows but rarely, if ever, would that be useful. Each window would be too small 
and the screen would be too cluttered. Practically, there should not be more than five. In 
the examples in Section 1, there are lines marking the division between lop and bottom 

* windows. This is a trailer line specified in the exec_com or program. It is not necessary, but 
does make the delineation obvious and aids readability. Windows may not overlap. Each 

I window has its own extent (height and width) and location (the position of its home on the 
screen). Windows can change their extent and location as long as they never overlap. The 
initial extent and location of a window is determined in the attach description of the window. 



Window Operations 

The rest of this section discusses the operations of window_call and window_ that are 
most essential. These include: create, change, destroy, and clear. Specific examples are given 
for exec_com and PL/I applications. 
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CREATE WINDOW OPERATION 

Now you need to define windows and this is done with arguments to window_call or 
with the entry points of the window_ subroutine. The first action discussed is create_window. 
Part of the creation process is the naming of windows. Windows are associated with iox_ 
I/O switches. The "name of the window" is just the name of the switch, or as it is 
sometimes called, the iocb name. Since many Multics commands and subroutines make use of 
the standard switches user_io, user_input, error_output, and user_output, it is usually necessary 
to have these switches connected 4o stMne window. This is done by window_eall invoke or 
video_utils_$turn_on_login_channel. By convention, the bottom window of the screen is used 
for user_i/o. 



Important Window Requests 

Before a window can be created you must decide on its starting line number as 
discussed above in "Attaching Video" and its length (in number of lines). As mentioned 
earlier, it is customary to get space for a new window from the user_i/o window and to 
position the new window at the top of the user_i/o window. Therefore, one of the first 
things to do is find out where the user_i/o window is. Once this is known you must 
determine just how high, in lines, the new window must be and shrink the user_i/o window 
by that amount. It is a good idea to always check to make sure there is enough space left 
in the user_i/o window to allow meaningful communication once it has been shrunk. In our 
examples we will insist on at least a five line user_i/o window. 



2-9 



CP51-02 



To do all that has been discussed so far in an exec.com, we would have the following: 

&- stored in the default value segment as the__menu. 

&set io__start &[window_call get__f i rst_l i ne] 
&set io_height &[wi ndow_cal 1 get_window_height] 
&set menu__height &[menu_descr ibe the_menu -height] 

&- Now calculate the new positions of both windows. 

Sset menu__start &(io_start) 

&set io_start sCplus &(io_s1iart) S (menu_hei ght) ] 
&set io_height & [minus &(io_height) & (menu_height) ] 

&- The label referenced below would, of course, need to be 
&- defined and would include an appropriate error message. 

&if &[nless &(io_height) 5] 

Sthen Sgoto USER_I /0_TOO_SMALL 

&- Now shrink user__i/o 

window__can change_wi ndow -line 6(io_start) -height &(io_height) 
&- And define the new window, called able 

window_call create_wi ndow -io_switch able -line S (menu_star t) -height 
6 (menu_height) 



The real work of creating the new window above was done by the window_call 
command with the create_window argument This command created the necessary iox_ I/O 
switch attachments to make "able" an I/O switch which describes a video system window that 
occupies the first "menu_height" lines of what was user_i/o. 
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THE PL!/ EXAMPLE 



A window can be created either at command level or from a PL/I subroutine. To do 
the same thing in PL/I you would use the following code fragment: 

/ii Get the variables initialized. We assume the menu has '</ 
/* been created and the requirements for the menu are */ 
/* stored in the menu__needs structure (see menu_ for del) */ 

^include wi ndow_control__i nf o; 

del 1 lo__window_info like (window_posi tion_info) ; 
del 1 menu_wi ndow_i nfo like (window_posi tioh_info) ; 

io__wi ndow__i nfo. vers ion = window__posi tion__info_version_l ; 
call iox__$control (iox__$user_io, "get__wi ndow_i nfo", addr 

( i o__wi ndow_i nfo) , code) ; 

if code ^= 0 then do; 

process the error 
end; 

menu_wi ndow__i nf o = io_wi ndow_i nf o; 

/* Now calculate the new positions of both windows. */ 

menu__wi ndow_i nf o.or i gi n. 1 i ne = io_wi ndow_i nf o.or i g i n . 1 i ne; 
io__window_info.or igin. 1 ine = io_wi ndow__i nfo.or i g i n. 1 i ne 

+menu_wi ndow_i nfo. extent. height; 
io_window_i nfo. extent. height = io_window_i nfo. extent. height 

-menu_wi ndow_i nfo. extent .hei ght; 
if io_window_i nfo. extent. hei ght < 5 
then do; 

if code ^= 0 then do; 

process the error 

end; 
end; 

/* Now shrink user__i/o */ 

call iox_$control (iox_$user_io, "set__wi ndow_i nf o" , addr 
(io_window_info) , code); 
if code ^= 0 then do; 

process the error 

end; 

/* And define the new window */ 

call wi ndow_$ create (video__data_$terminal_iocb, addr (menu_wi ndow_i nf o) , 
menu_w i ndow_ i ocbp , code) ; 
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CHANGE WINDOW OPERATION 



In the above examples we have seen that it was necessary to change or shrink the 
user_i/o window in order to create a new window. When we discuss destroying windows 
below we will see a need to expand the iiser_i/o window to recover the space freed by the 
destruction of a window. 



Command level changes are done with the window_call keyword change_window. In 
PL /I the changes are made by the set_window_info control order. In general this will be 
preceded by a get_window_info control order and some calculations. 



DESTROY WINDOW OPERATION 

Once a window is no longer needed it must be destroyed, i.e., the I/O switch must be 

closed and detached thus freeing up the space on the screen that was occupied by the 
window. In addition, this space should be returned to some active window so that it can be 

used. If the freed space is adjacent to the user_i/o window it should be consumed by that 

window, but it can be added to any adjacent window. In our examples we will add it back 
to user_i/o. 



To reverse the effects of the exec_com window creation example above we would have: 
6- destroy the able window 
5- and let user_i/o have the space back 
Sset io_start S (menu_start) 

&set io_height 6 [pi us & (menu_hei ght) & ( i o_hei ght) ] 
6set menu__start 0 menu_height 0 

window_call change_wi ndow -line &(io__start) -height 5(lo_height) 

In PL/ I we would have: 

/" destroy the able window «/ 

call wi ndow_$destroy (...)» 
if code ^= 0 then do; 

process the error 

end; 
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/* and let user_i/o have the space back */ 

io_wi ndow^i nf o.or i gi n . 1 i ne = menu^wi ndow_i nf o.or i gi n. 1 i ne; 
i o_w i ndow_ info. ex ten t .height = menu_w i ndow_ info. ex ten t .height 
+io_wi ndow__info. ex tent, height; 

call iox__$control (lox_$user_io, "set_window_info", 
addr (io__window_info) , code); 
if code ^= 0 then do; 

process the error 

end; 



CLEAR W/ A/DOW OPERATION 

Another very useful operation is the clear_window operation. This clears the entire 
window to all spaces and leaves the cursor positioned at the upper left hand corner of the 
window. There are other clearing operations, but this one is the simplest and most useful. 



From command level we can clear the user_i/o window by: 
w i ndow_ca 11 c 1 ear_w i ndow 

If we had wanted to clear, say the able window, we would have included the -io_switch 
control argument specifying able as the window to operate on. 



This same effect, clearing the able window of our examples, can be accomplished from 

PL/I by: 

call wi ndow_$clear_wi ndow (menu_wi ndow__iocbp, code); 
if code ^- 0 then do; 

process the error 

end; 



The clear_window operation is useful when an application wants to start with a clean 
slate in the user_i/o window. For example, before printing out a description of some menu 
option it might be desirable to clear the user_i/o window. 
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OTHER USEFUL OPERATIONS 



Once window status is set, any operation performed on that window (except for a create 
or destroy operation) returns the status code video_et_$window_status__pending until the status 
is reset To reset the status, perform a get_window_status control order on the window 
switch. Refer to "Control Operations" for window_io_ later in this manual. 



There are many other operations that can be performed on windows using the video 
system. These are all described in the window_call conmiand in Section 5 or in the window_ 
subroutine description in Section 6 or the control orders or modes of the window_io_ I/O 
module in Section 7. 
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SECTION 3 
MENU APPLICATIONS 

This section discusses the use of function keys and the building of a menu application. 
It includes a sample exec_com, and PL/I programs. FORTRAN and COBOL programmers 
refer to Section 8 and Section 9, respectively. 



GUIDELINES FOR FUNCTION KEYS 

A set of keys that are integral to the menu system are the function keys. These are 
used to get information, move from one menu to another, or to exit from a menu and 
return to Multics command level. The reason that the function keys are used at all is to 
reserve the numbers for the options and also to eliminate the need to include these functions 
in every list of options in every meniL Ease of use is enhanced when the function keys are 
doing the same thing from application to application. The following example shows the 
definitions of the function keys in the "Games" menu. 

Press Fl - Gives definitions of the function keys 

Press F2 - Returns to the first menu 

Press F3 ~ Goes to the previous menu 

Press ?k - Returns to Multics command level 



If there are no function keys on the terminal, then the user could type specially 
assigned keys in sequence. In the following example the escape key has been chosen in 
conjunction with a letter that is related to the action performed. Hie selection would then 
be: 

ESC d - Gives definitions of the function keys 

ESC f - Returns to the first menu 

ESC p - Goes to the previous menu 

ESC r - Returns to Multics command level 



Since not all terminals have function keys, you must include a call to 
ttt_info_$function_key_data (described in Multics Subroutines and 110 Modules, Order No. 
AG93) in your program, which will return information about the terminal being used. This 
information covers whether or not there are function keys and how many there are. 



For those terminals without function keys, or which do not have enough, you must 
designate keys to be used in their place. It is helpful to the end user if the first of these 
keys is a "special" key such as the escape key. This should be followed by a regular key that 
is somewhat related to the action to be performed. You can use a single key, but the 
advantage of two in sequence is that it does not interfere with the option numbers or letters 
that have been used. The sequence can also be more than two keys, but the longer it is the 
greater the chance of typing errors. 
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Summary of function key recommendations: 

• Assign the same meaning to specific keys for every menu. 

• Include a call to ttt_info_$function_key_data in your program. 

• There is no command level interface to ttt_info_$function_key_data so this 
cannot be done with exec_com. 

If function keys are not available, follow the above suggestions plus: 

• Use a combination of characters such that the first character is not the same 
as any menu option character. A suggestion is using a special key (not @ or 
#) such as <£SC> in conjunction with a character related to the action 
performed. For example, <ESC> p for previous menu, or <ESC> r for 
returning to command level. 

• Do not use numbers or single letters as they are reserved for options. 

• Do not use two digit numbers because only the first digit is "heard" and an 
option would therefore be selected. In other words, if you have a function 
numbered 12 only the first digit is processed so option 1 would be selected. 



THE EXEC_COM EXAMPLE 

There are four ways in which menu applications may be built one using exec_com and 
written in the Multics command language; the others using PL/ 1, FORTRAN or COBOL 
programs. The exec_coms provide a quick and easy way to implement very simple menu 
applications whereas PL/ 1, FORTRAN or COBOL programs provide for more powerful and 
robust ones. The Multics menu system provides commands and subroutines to facilitate either 
type of implementation. 



Below is an example of an exec_com interface to the menu system. It is a very simple 
application and it illustrates how you can begin. The example is a document menu for 
everyday office use. It is called "Document System". The user will be able to enter, edit, 
display, print, list or delete documents. The last option available is to exit the document 
system. So, there are seven options in all and they will be displayed in the top window. 
Since you will probably want them displayed in the fewest number of lines possible, make 
space in this window for 6 lines allowing for the headers, the trailers, and the list of menu 
options printed in two columns. The area from line seven to the end of the screen is the 
user_i/o window. To see how the standard I/O switch attachments change when you use an 
exec_com to create a menu, refer to Appendix A, especially Figure A-3. Line numbers are 
used in this example to indicate new lines, e.g., line 18 is all one line in the exec.com and a 
new line does not occur till the number 19 appears. Line numbers should not be included in 
your exec_com. 
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1 Sversion 2 

2 Strace off 



6- First we will see if the video system is enabled 
&- in the users process. This is done by checking 

5- to see if the i/0 switch user__termi na1_ is 

6- attached. If it isn't we invoke the video 

&- system. We need to do this so that we can later 
&- return the user to his/her normal environment. 

3 &set al ready__video S[io attached user_termi nal_] 

h &\f £[not S (al ready__video) 3 
5 &then window_call invoke 

&- Now we will create our demonstration menu. In 

&- real applications this menu would most likely be 

&- saved in some value segment containing other menus 



6 menu_create main -option "enter new document" 
-option "edit old document" -option "print document on 
terminal" -option "print document on printer" -option 
"list documents" -option "delete document" -columns 2 
-header "«< DOCUMENT SYSTEM »>" -center__headers 
-trailer "-" -trailer "USE FUNCTION KEY 1 TO EXIT" 
-trailer "-" -center_trai lers -pad "-" 

5- Here we determine where the windows will go. 

6- What we will attempt to do is split the user_]/o 
&- window into two windows. The top window is named 
&- using a unique name to avoid conflict with other 
&- I/O switch names in the process and will contain 
&- the menu. The bottom window will be user_i/o. 

&- This split of user_i/o is done to allow this 

&- application to run while other video applications 

5- windows exist on the screen. 

7 &set menu_start &[wi ndow_cal 1 get_f i rst__l i ne] 

8 &set menu_height &[menu_descr ibe main -height] 

9 &set io_start 5 [pi us 6 (menu_start) & (menu_hei ght) ] 

10 &set io_height & [minus [window_cal1 get_wi ndow_he i ght] & (menu_he i ght) ] 

6- We must have at least 5 lines left in user_i/o. 
&- This is an arbitrary limit that this exec_com 
&- will enforce. 

n &if &[nless &(io_height) 5] 

12 &then Sdo 

13 Sprint There is not enough room on the screen to run. 
1 k &qu I t 

15 &end 

&- Now establish the window to be used to display 

5- the menu. It takes its space on the screen from 

6- user_i/o, so first shrink user l/o. The menu 
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&- window is given a name using the unique active 
&- function to avoid conflicts with I/O switch names 
&- already in existence. 

16 window_call change__wi ndow -line 6(io__start) -height &(io_height) 

17 &set menu_switch & [unique] .menu 

18 window__call createjwi ndow -io^switch 6 (menu__swi tch) -line 
& (menu_start) -height & (menu_height) 

&- We are now ready to display the menu and get a 

choice. We must display the menu each time 

&- through the loop due to the fact that 

&- menu__get_choi ce will modify the menu display in 

&- the window. We will set a local exec_com 

&- variable to the choice made just in case we want 

&- it in the future (in this example we don't, but 

&- its a good idea anyway). 

19 Slabel GET-CHOICE 

20 menu_di splay main -io_switch & (menu_swi tch) 

21 6set choice &[menu__get__choi ce main -io_switch & (menu__swi tch) ] 

&- Now that we have either (1) a valid menu choice 
&- in the form of a decimal integer, or (2) a 
&- function key selection in the form "F" followed 
&- by the function key number, let's perform the 
&- requested action. 

22 &goto CHOI CE-& (choice) 

&- This choice is "enter a new document." It will 

5- first create the new document and then enter ted 

6- to allow entry of the text. Before doing 

6- anything, this action, like all others, will 

6- clear the user_i/o window. This gives a feeling 

&- of starting some new action that we want at this 

&- point (this is done for all actions). 

23 &label CHOICE-1 

2k window__call clear_window 

25 io control user_i/o reset_more 

26 do "create &tl;ted -pn &61" [response "new document name:"] 

27 &goto GET-CHOiCE 

6- This choice is "edit an old document." It will 
&- enter ted for editing of the requested document. 

28 Slabel CHOICE-2 

29 window_call clear_wlndow 

30 io control user_i/o reset_more 

31 ted -pn [response "old document name:"] 

32 &goto GET-CHOICE 
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6- This choice is "print document on terminal." It 

will just print the specified document in the 
S- user_i/o window. 

33 Slabel CHOICE-3 

34 w i ndow_ca 11 c 1 ear_w i ndow 

35 io control user_i/o reset_more 

36 print [response "document name:"] I 

37 &goto GET-CHOICE 

5- This action is "print document on printer." It 

6- will simply enter a dprint request of the 
&- specified document. 

38 &1abe1 CHOICE-^ 

39 window__call clear_window 

ho io control user__i/o reset__more 

41 dprint [response "document name:"] 

kl 6goto GET-CHOiCE 

&- This is the "list documents" action. It will 
&- simply list the names of all of the documents 
&- defined. Our convention for document naming is 

simple - any single component segment name will 

do. 

43 &labe1 CHOICE-5 

hh w i ndow_ca 11 c 1 ear_w i ndow 

kS io control user__i/o reset__more 

46 list * -name -primary 

47 Sgoto GET-CHOICE 

&- This is the "delete document" action. It deletes 
&- the document specified by the user. 

48 &1abe1 CHOiCE-6 

49 w i ndow_ca 11 c 1 ear_w i ndow 

50 io control user_i/o reset__more 

51 delete [response "document name:"] 

52 &goto GET-CHOICE 

5- This is the action for function key #1. This 
action exits the document subsystem. At this 

6- point we will destroy the menu window and either: 
&- (1) return the user__i/o window to its former 

&- state, or (2) revoke the window system entirely. 
&- This choice is based on whether the video system 
&- was in effect when we started this exec_com. 

53 &labe1 CH0ICE-F1 
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5^ window__ca11 delete_wi ndow -io__switch £ (menu_swi tch) 

55 &if & (al ready_video) 

56 &then &do 

57 window_call change__wi ndow -line S (menu__start) -height 
&[plus & (menu_hei ght) 6 (io_height) ] 

58 window_call clear_window 

59 Send 

60 &else window_call revoke 

61 &quit 

&- One last thing to check for are undefined 
&- function keys. For these we will simply ring the 
&- bell (in the video system tradition that's what 
&- it does for undefined control character input 
&- sequences) . 

62 & label CHO I CE-& (choice) 

63 wi ndow cal 1 bel 1 

64 Sgoto GET-CHOICE 



THE PL/I EXAMPLE 



Below is the PL/ 1 example setting up the same menu, Document System. Your first 
reaction may be that it is far more complicated and much longer than the exec_com example. 
If the document system menu were going to staji. this simple it probably wouldn't be 
reasonable to do it in PL/ 1. But if the menu is going to be enhanced with more capabilities 
and power, PL/ 1 is the better approach. You can add a great deal of versatility and correct 
errors with a PL/ 1 application, something that just cannot be done with exec_com. 

mdl : 

proc 0 ; 



/* Automatic */ 



choice fixed bin; 

choices (6) char (30) var; 

code fixed bin (35); 

f key bit (1) al i gned; 

headers (1) char (30) var; 

key_shi f t_idx fixed bin; 

menu_io ptr init (null); 

menu_io__swi tch_name char (32); 

menu__ptr ptr; 

my_area area (4095) » 

1 my_menu_f ormat like menu__f ormat; 

1 my_menu_requi rements 1 ike menu_requi rements; 

1 new_wi ndow_i nf o 1 ike window_posi tion^info; 

reason char (512) ; 

term_type char (32) ; 

trailers (2) char (30) var; 

1 user__io_wi ndow__i nf o 1 ike window_posi tion_info; 
vi deo_was_al ready_on bit (1) aligned; 
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/* Based */ 

del 1 fkey_data like function__key_data based (f unct lon_key_data_ptr) ; 
/* Builtfn */ 

del (addr, empty, length, null) builtin; 

/* Conditions */ 

del eleanup condition; 

/* Entries */ 

del eom_err__ entry () options (variable) ; 
del ioa__ entry () options (variable); 
del ttt_i nf o_$f unct ion_key__data entry 

(char (''<), ptr, ptr, fixed bin (35)); 
del unique_chars_ entry (bit (*)) returns (char (15)); 
del user_i nf o__$termi nal__data 

entry (char (*) , char (*) , char (*) , fixed bin, char (*) ) ; 
del video_uti 1 s_$turn_of f__logi n_ehannel entry (fixed bin (35)); 
del video_uti 1 s_$turn_on_logi n__channel entry (char (*) , fixed bin (35)) » 

/* External */ 

del video_data_$termi nal_iocb pointer external; 
/* Static */ 

del ALTERNATE_F1_STRING char (2) static options (constant) init ("tj) ; 

/* ESC q */ 

del ME char (3) static options (constant) init ("mdl") ; 

del M!N_USER_IO_HE!GHT fixed bin static options (constant) init (5); 

del USER__IO char (8) static options (constant) init ("user_i/o") ; 

video_was_al ready_on = (video_data_$termi nal_iocb ^= null); 

on cleanup call terminate_sys () ; 

/* Set up the menu. */ 

/* Invoke the window system if it's not. already invoked. >'</ 

if '^video_was_al ready^on then do; 

call vldeo_uti ls_$turn__on__logi n_ehannel (code, reason); 
if code 0 then 

call quit (code, reason); 

end; 

call window_$clear__window (iox__$user_l o, code); 
if code ^= 0 then 

call quit (code, USER__IO); 

/* Create the menu. */ 
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choices (1) = "enter new document"; 

choices (2) » "edit old document"; 

choices (3) = "print document on terminal" 

choices {h) = "print document on printer"; 

choices (5) = "list documents"; 

choices (6) « "delete document"; 



headers (1) = "«< DOCUMENT SYSTEM »>"; 
trailers (1) = "USE FUNCTION KEY 1 TO EXIT"; 
trailers (2) = "-"; 

call user_info_$terminal_data ((""), term_type, ("") , (0), ("")); 
call ttt__i nfo_$f unct ion_key__data (term_type, addr (my__area) , 
f unct ion_key_data_ptr, (code)}; 

if code ^= 0 then 

call quit (code, "Unable to determine terminal type") 

/* See if we have to use an escape sequence for Fl */ 

if fkey_data. highest < 1 then do; 

trailers (1) = "USE ESC-q TO EXIT"; 
free fkey_data in (my_area) ; 
f unction_key_data_highest = 1; 

allocate fkey__data in (my_area) set (f unct i on_key_data_ptr) ; 
fkey_data. vers ion = function_key_data_version_l ; 
fkey_data.seq_ptr = addr (ALTERNATE_F 1_STRI NG) ; 
fkey_data.seq_len = length (ALTERNATE_F 1_STRI NG) ; 
do key_sh i f t__idx = 0 to 3; 

f key_data . home . sequence__l ength 

(key_shi f t_idx) = 0; 
f key_data. left.sequence_l ength 

(key__shif t_idx) = 0; 
f key_data .up.sequence_l ength 
(key_shi f t_idx) = 0; 
f key_data . r i ght . sequence_1 ength 

(key_shi f t_idx) = 0; 
f key_da ta . down . sequence_l ength 

(key_shi f t_idx) = 0; 
f key_data . f unct i on_keys . sequence__l ength 

(0, key_shi f t_idx) = 0; 
f key__data . f unct i on__keys . sequence_l ength 
(1, key_shi f t_idx) = 0; 

end; 

f key_data.f unct ion_keys.sequence_index (1, KEY_PLAIN) = 1; 
fkey_data.f unct ion_keys.sequence_l ength (1, KEY__PLAIN) = 
1 ength (ALTERN ATE_F 1__STR I NG) ; 

end; 

my__menu__format, vers ion « menu__format__version_l ; 
my_menu_format .max_width = 80; 
my_menu_f ormat .max_hei ght = 6; 
my_menu_f ormat .n_columns = 2; 
my_menu_f ormat .center_headers = "l"b: 
my_menu_format.center_trai lers = "l"b; 
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my_menu_format.pael = "0"b; 
my_menu_format.pad_char = 

my_menu_requireinents. vers ion = menu_requi rements_version_l ; 

Now we can create the menu. V 

call menu_$create (choices, headers, trailers, addr 
(my__menu_format) , 
MENU_OPTION_KEYS, addr (my_area) , addr (my_menu_requi rements) , 
menu_ptr , code) ; 
if code 0 then 

call quit (code, "Unable to create menu."); 

/* Now carve the menu I/O window out of the user__i/o window. 
This program insists that the user_i/o window must be at 
least 5 lines high after this is done. The menu I/O window 
is given a unique name so that this program can be invoked 
recursively. */ 

user_io_window_info.version = window__posi tion_info_version__l ; 
call iox_$control (iox_$user__io, "get__wi ndow__i nfo", 

addr (user_io_wi ndow_i nf o) , code); 
if code ^= 0 then 

call quit (code, USER_IO); 

if user_io_window_ info. height 

< my_menu__requi rements. 1 i nes_needed + Ml N_USER_I 0_HE I GHT then 
call quit (0, "Window ""user_i/o"" is too small."); 

new_wi ndow_i nfo. vers ion - wi ndow__pos i t ion_i nfo_version__l ; 
new_wi ndow_i nf o. 1 i ne = 

user_io_wi ndow_i nfo. 1 i ne + my_menu_requi rements . 1 i nes_needed; 
new__wi ndow_i nfo. width = user_io_wi ndow_i nfo. width; 
new_wi ndow_i nfo.hei ght = 

user_io_window__ info. height - my_menu_requirements. 1 ines_needed; 
call iox_$control (iox_$user_io, "set_wi ndow__i nf o" , 
addr Cnew_wi ndow_i nf o) , code); 
if code ^= 0 then 

call quit (code, "Unable to shrink window ""user_i/o"".") ; 

menu_io_swi tch_name = "menu_i/o_" || unique_chars_ ("0"b) ; 

call iox__$f ind_iocb (menu__io__swi tch_name, menu_io, code); 
if code ^= 0 then 

call quit (code, "Unable to get lOCB pointer for menu window."); 

new_window_info. 1 ine = user_io_window_info. 1 ine; 

new_wi ndow__i nfo. height = my_menu_requi rements. 1 ines__needed; 

call wi ndow_$ create (vi deo_data_$termi nal_i ocb, 

addr (new__wi ndow_i nf o) , menu_io, code); 
if code 0 then 

call quit (code, "Unable to create the menu_i/o window."); 
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Now that we have the window system all set up we can go ahead and 
display the menu and start processing. */ 

call menu_$display (menu_io, menu_ptr, code); 
if code ^= 0 then 
. call quit (code, "Unable to display menu."); 

/* Now start processing input from the user. */ 

do while ("l"b) ; 

Get an option number or function key value from the user. ^/ 

call menu_$get_choice (menu_io, menu_ptr, f unct ion_key_data_ptr , 
fkey, choice, code) ; 

/* Perform an action depending on the user's selection. */ 

if code ^= 0 then 

call quit (code, "Unable to get choice."); 
if fkey then 

if choice = 1 then do; 
call termi nate_sys (); 
if video_was_al ready_on then 

call wi ndow__$ clear _wi ndow (i ox_$user_i o, (0)); 
goto EXIT; 
end; 

else call window_$bell (menu__io, (0)); 
else do; 

if choice = 1 then 

call create__document () ; 
else if choice = 2 then 

call ed i t_document () ; 
else if choice = 3 then 

call d i spl ay_document () ; 
else if choice = h then 

call pr i nt_document () ; 
else if choice = 5 then 

call 1 i st_documents () ; 
else if choice = 6 then 

call delete_document () ; 
else call window_$bell (menu_io, (0)); 

end; 

end; /* do whi le */ 

EXIT: 

return; 

/* procedures for options */ 

create_document: 
proc 0 ; 

call ioa_ ("To be provided."); 
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end create document; 



edi t_docufnent: 
proc 0 ; 

call ioa_ ("To be provided.'*); 

end edit document; 



di sp]ay_document: 
proc 0 ; 

call ioa_ ("To be provided."); 

end display_document; 



pr int_document: 
proc 0 ; 

call ioa__ ("To be provided."); 

end pr i nt_document; 

1 i st_documents: 
proc 0 ; 

call ioa__ ("To be provided."); 

end 1 i s t_docunjents ; 



delete_document: 
proc 0 ; 

call ioa_ ("To be provided."); 

end del ete_document; 

/* internal procedures */ 

/* This procedure is called whenever we must leave the 
subsystem we have set up (if an error occurs or the 
user wants to leave). It rearranges things back to 
the way they were before. */ 

terminate_sys: 
proc () ; 

if menu__io ^- null () then 

call wi ndow_$destroy (menu_io, (0)); 

if vi deo_was_al ready__on then 

call iox__$control (iox_$user__io, "set_wi ndow__i nfo". 
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addr (user__io_wi ndow_i nfo) , (0)); 
else call video_uti ls__$turn_off__login__channel ((0)); 

end terminate_sys; 

qui t: 

proc (code, explanation); 

del code fixed bin (35); 
del explanation char (*) ; 

call termi nate_sys () ; 

call com_err__ (code, ME, explanation); 

go to EXIT; 



end 


quit; 


%i nclude 


i ox_dc 1 s ; 


%page; 




%i nclude 


wi ndow_dcl s; 


%page; 




%i ncl ude 


f unct i on__key_data ; 


%page; 




%i nclude 


inenu_dc 1 s ; 


%page; 




%i nclude 


wi ndow_control_i nf o; 


end 


mdl ; 
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SECTION 4 
VIDEO SYSTEM DETAILS 



This section describes the Multics Video System. The Multics Video System is an 
upwards compatible extension to the Multics Communications System. The basic features of* 
the Multics Video System are: 

• Ehviding the user's terminal into one or more windows. Windows are described 
in detail in Section 2 of this manual. 

• A powerful real-time editor for input lines. The erase and kill characters take 
effect as soon as they are typed. Additional characters allow the user to delete 
words and to retrieve deleted text. 

• Flexible control over output When a window is full of output it can scroll 

(removing lines from the top of the window, adding new ones to the bottom), 
or wrap (output begins at the top of the window, optionally clearing the 
window first). 

• MORE Processing. The video system pauses when a window is full of output 

until the user indicates that the window has been read. This is an extension to 
End Of Page processing. The user can also choose to discard unseen all 
pending output 



REAL-TIME EDITING 

Real-time editing is markedly different from usual Multics editing. All editing requests 
take effect immediately. The screen changes to show the effect of the characters or lines 
deleted. In addition, the set of editing characters expands to include several control 
characters. 



Control characters are characters entered using the control key.- The control key is a 
key that acts like the shift key. By itself it generates no characters; it is used to change the 
meaning of some other key. When the key "A" is typed while the control key is held down, 
the character sent by the terminal is control A, which is written as '^A. The control 
characters are the first 32 ASCII characters, 000 through 037 octal. 



Alphabetic characters are given in capitals, but either an upper or lower case letter (as 
for N or n) can be used with default escape sequences. If an upper case letter is used with 
a user-defined sequence, both the upper and lower case keys must be bound in order for 
both keys to work. The letters ESC represent the escape key. For ESC F, you would press 
the escape key, release it and type an f or F. 
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Although most Multics users keep the system default erase (#) and kill (@) symbols, 
the video system recognizes and then assumes the values of any erase and kill characters that 
may have been set via the set_tty conmiand. 



The Erase Diaracter 

The erase character removes the character to the left of the cursor. The cursor moves 
to the left, and exactly one character is deleted. This is different from usual Multics editing 
where an erase character typed after white space deletes all whitespace, and otherwise deletes 
all characters from a column position. The erase character is settable for each window. In 
addition, the DEL character and the backspace character (\010) are always erase 

characters. 



The Kill Character 

The kill character deletes the entire line to the left of the cursor. The cursor then goes 
back to the beginning of the line. Again, this happens immediately. The deleted line is 
saved, and can be recovered. See "Retrieving Deleted Text" below. The kill character is 
settable per-window. 



The Line Editor 

Additional editing is possible using sequences of one and two characters. The 
two-character sequences all begin with the ASCII ESC character, [, octal 033), which is not 
the same as the Multics input escape character ("\"). 



MOVING THE CURSOR 

The line editor can move the cursor forward or backward within the current line while 
repositioning the cursor either a character at a time or a word at a time. A word is an 
unbroken string of uppercase and lowercase alphabetics, numerals, underscores, backspace 
characters, and hyphens. (This is the default definition of a word, which can be changed 
with the set_token_delimiters order, described in the window_io_ writeup.) The cursor can 
also move explicitly to the beginning or the end of the current line. The requests that 
perform these actions are listed under "Other Editor Requests" below. 



DELETING CHARACTERS AND WORDS 

The line editor can delete a single character or an entire word at a time. Various 
editing requests described below can delete the character or word immediately to either the 
left or the right of the cursor. The deleted text (only words, not characters) is saved and 
can be retrieved. For example, typing ESC DEL (or ESC followed by the current erase 
character) deletes the word to the left of the cursor. The word is saved on the kill ring (see 
below). 
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RETRIEVING DELETED TEXT 



Text deleted by the word and line kill characters is saved, and can be restored. The 
text is saved on a kill ring. A kill ring is a set of kill slots. Each slot holds deleted text 
Successive word kills share one kill slot, so if several words are deleted one after another, all 
of them will be retrieved by a single retrieve command. 



Deleted text is saved with previously deleted text if two delete characters are typed in 
succession. If intervening characters are typed, the kill ring is rotated: a new slot is selected 
to hold saved text 



Text is entered when the user types text followed by a carriage return. Each input line 
is added to the kill ring. This provides editing of the previous input line. 



The following control characters are used to retrieve deleted text: 

'^Y (or yank) retrieves deleted text from the kill ring. This is the only way 

to recover from an erroneous kill character. 

ESC Y can be typed only after either ^Y or ESC Y. It deletes the text just 

retrieved, without saving it on the kill ring, rotates the ring (to the 
next most recently killed text) and retrieves the text from the new top 
slot 



The following example is given in triplets. The first line shows what the user types, the 
second line shows what one line of the display looks like afterwards, and the third line (or 
lines) shows the kill ring. The top item on the kill ring is at the top of the colunm. 

User Types: This is a sentence 
Display is: This is a sentence 
Kill Ring: <empty> 

NOTE: The kill ring is empty because the user has just invoked the video system. 

User Types: ESC DEL 
Display is: This is a 
Kill Ring: sentence 

One word is deleted, and it begins the kill ring. 

User Types: ESC DEL 
Display is: This is 
Kill Ring: a sentence 
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Another word is deleted; it is merged into the same kill slot 

User Types: an example sofa 

Display is: This is an example sofa 
Kilt Ring: a sentence 

User Types: ESC DEL 

Display is: This is an example 

Kill Ring: sofa 

a sentence 

This deleted word is not merged, because there has been typing since the last kill command. 
There are now two slots on the kill ring. 

User Types: of '^Y 

Display is: This is an example of sofa 
Kill Ring: sofa 

a sentence 

The top kill slot is yanked back. 
User Types: ESC Y 

Display is: This is an example of a sentence 
Kill Ring: a sentence 
sofa 

The kill ring is rotated, the previously yanked contents are deleted from the line, and the 
new top item from the ring is yanked to replace it 



If a carriage return were typed at the end of "This is an example of a sentence", the 
kill ring would then contain a new slot containing the entire input line. 



Other Editor Requests 

Alphabetic characters are given in capitals, but either an upper or lower case letter 
(ESC F or ESC f) can be used. The following control characters are also recognized by the 



line editor: 

'^L Clears the window and redisplays the input line. 

'^Q "quotes" the next character, causing it to have no special 

meaning. This is useful for entering control characters. It serves 
some of the same purposes as the input escape character (\). 

'^F moves the cursor forward one character. 

'^B moves the cursor backward one character. 

ESC F moves the cursor forward one word. 

ESC B moves the cursor backward one word. 
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moves the cursor to the b^inning of the current line. 


'^E 




moves the cursor to the end of the current line. 


'^D 




deletes the current character (deletes forward). 


DEL. # 


deletes the character to the left of the cursor (deletes backward). 


ESC 


D 


udcies liic wurrcnL woru lorwaruj. 


ESC 


DEL. ESC # 


ueieies uie woru lo uie leii oi me cursor voeieies oacKwaru;. 


ESC 


C 


capitalize initial word. 


ESC 


u 


capitalize word. 


ESC 


L 


lower case word. 


ESC 


T 


twiddle word. 



By default, no other control characters have meaning. If any are typed, the only action 
they cause is an audible alarm. You can create additional editor requests by writing PL/1 
programs that conform to a standard calling sequence (see "Writing Editor Extensions"). 



The set of characters used to define a word for control characters such as ESC F can 
be changed via the set_token_characters control order. See the description in the window_io_ 
I/O module later in this manual. 



Writing Editor Extensions 

The video system provides a full input line editor, including the ability to edit in the 
middle of the line. Of course, there are many potential editor functions that people might 
like to use (see the Emacs Text Editor Uset§ Guide Order No. CH27), and not all of these 
are provided. Rather than attempt to anticipate every possible editor request, the video system 
allows users who are familiar with PL/1 to write tiieir own editor requests and associate 
sequences of keystrokes (key binding) with these requests. 



The key binding mechanism can be used for a wide variety of applications. Since editor 
requests are executed immediately by single or multiple keystroke sequences, highly interactive 
facilities can be built into the input line editor. 



LINE EDITOR ROUTINES 

Editor request routines are PL/I programs that conform to a standard calling sequence. 
The request procedure is given complete control of the input buffer and can add or delete 
characters or modify the current contents of the buffer. The video system editor's redisplay 
facility manages all display updates; the individual editor .routines need no knowledge of the 
video enviroment or the screen contents. 
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A library of editor utility routines is provided (see "Editor Utilities"). These can be 
called by user-written editor routines to perform such actions as insertion and deletion of 
text from the buffer, manipulation of the kill ring, and manipulation of words within the 
input buffer. 



A line editor routine is declared as follows: 
USAGE 

del twiddle_words entry (pointer, fixed bin (35))* 

call twiddle__words (1 ine_edi tor__info_ptr, code); 

ARGUMENTS 

line_editor_inf o_ptr 

is a pointer to the line_editor_info data structure (described below). 

code 

is a standard status code. (Output) If the status code returned by the editor routine is 
error_table_$action_not_performed, the editor will ring the terminal bell to indicate that 
the editor routine was used improperly. Any other code will reported in a more drastic 
manner, via the sub_err_ mechanism. 



The line_edilor_info structure (declared in window_line_editor,incl.pll) is declared as 
follows: 



del 111 ne_ed i tor_i nf o 

2 version 

2 iocb_ptr 

2 repet i t ion_count 

2 flags, 

3 return_f rom_ed i tor 

3 merge_next_k i 1 1 

3 old_merge_next_k i 1 1 

3 last_ki 1 l__di rection 

3 numarg_given 

3 suppress_redi splay 

3 pad 

2 user_data_ptr 

2 cursor_index 

2 1 i ne_length 

2 input_buffer 

2 key_sequence 



aligned based (1 i ne_edi tor_i nfo_ptr) , 
char (8) , 

pointer, /* to current window */ 
fixed bin. 



bi t (1 
bit (1 
bit (1 
bit (1 
bit (1 
bit (1 
bit (30) 



unal i gned, 
unal i gned, 
unal i gned, 
unal i gned, 
unal i gned, 
unal i gned 
unal igned. 



pointer, /* for 
fixed bin(21) , 
fixed bin(21) , 
character (1024) 
character (128) ; 



user state info */ 



unal igned; 



del 1 ine_edi t6r__i nput_l ine char (1 ine_editor_lnfo.l ine_length) based (addr 
(1 ine__edi tor^info. input_buf f er) ) ; 

del 1 i ne_edi tor_i nfo_version_2 char (8) static options (constant) init 
("lei00002") ; 
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STRUCTURE ELEMENTS 



version 

is string for this structure. (Input) The current version string, "lei00002", is the value of 
the variable line_editor_info_version_2, declared in the same include file. 

iocb_ptr 

is the pointer to the current window. (Input) 
repetition_count 

is the value of the numeric argument specified by the user, and is undefined if no 
numeric argument was specified (i. e., numarg^ven flag = "0"b). (Input) 

return_f rom_editor 

is a flag which is set by the editor routine if the editor invocation is to be terminated 
and the input line returned to the caller. The input buffer is redisplayed before the 
buffer is returned to the caller, unless overriden by the line_editor_info.suppress_redisplay 
flag. 

merge_next_kill 

is a flag which should be set when text is deleted and added to the kill ring if 
subsequent deletions are to be added to the same kill ring element (Input/ Output) This 
flag is managed by the editor utility routines. If the editor utility routines are used for 
all input buffer modifications, the user-written editor routine need never set this flag. 

old_merge_next_kill 

is an internal editor state flag and should not be modified, (not used) 

last_kill_direction 

direction of last kill (forward or backward). 

numarg given 

is "l"b (i.e. true) if a numeric argument was supplied by the user via ESC-NNN or '^U. 
suppress_redisplay 

is a flag that stops the redisplay of the input buffer when line_editor_info.return_from_editor 
is set 

pad 

reserved for future use. 
user_data_ptr 

points to a user data structure which the video system ignores, other than passing this 
pointer to requests that follow. 

cursor_index 

is the index of the character in the input buffer on which the cursor is currently 
located. (Input/Output) This index must be updated if characters are added or deleted 
before the cursor, or the cursor is moved by the editor routine. The cursor index must 
be no larger than one greater than the input_line_length. If the editor utility routines 
are used for all input buffer manipulations, the cursor_index will be updated 
appropriately. 
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line_length 

is a count of the number of characters in the current input line. (Input/Output) This 
variable must be updated if any characters are inserted or deleted from the input buffer. 
The value of the line.length variable must always be non-negative, and must never be 
larger than the length of the input buffer. If the line editor utility routines are used for 
all input buffer manipulations, the line__length variable will be updated automatically. 

input_buffer 

is a character string containing the current input line. (Input/ Output) Any manipulations 
may be performed on this string by the editor routine. It is recommended that the 
editor utility routines be used for all insertions and deletions to ensure that the various 
state variables and flags remain consistent The line_editor_input_line variable can be 
used to address the valid part of the input buffer as astring. 

key_sequence 

A character string that contains the sequence of key strokes that invoked this editor 
routine. 



Window Editor Utilities 

As was mentioned above, a library of editor utility routines is provided for the benefit 
of user-written editor routines. Some operations can be performed simply by a user-written 
editor routine. For example, to position the cursor to the end of the line, simply set the 
cursor_index variable to one greater than the value of the line_length variable. However, 
most actions are more complex than this and it is recommended that the editor utility 
routine be usai to perform most operations. The following is a description of these routines. 
In all cases, line_editor_info_ptr is the pointer to the editor data structure that is supplied as 
an argument to user-written editor routines. 

del wi ndow_ed i tor_uti 1 s_$ i nser t_text entry (ptr, char {*) , code); 
call window_edi tor_uti ls_$insert_text (1 i ne_edi tor_l nfo_ptr , "text", 
code) ; 

Inserts the supplied character string into the input buffer at the current cursor 
location. If the string is too large to fit in the remaining buffer space, the code 
error_table_$action_not_performed is returned. This routine updates the line_length 
field of the line_editor_info structure, and the cursor_index if necessary. 

del window_edl tor_uti ls_$delete__text entry (ptr, fixed bin, code); 
call wi ndow_edi tor_ut i 1 s_$delete__text (1 i ne_ed i tor_i nf o_ptr , count, 
code) ; 

Deletes a specified number of characters (supplied by the variable count) from the 
input buffer at the current cursor location. If there are not enough characters 
remaining between the cursor and the end of the line, error_table_$action_not_performed 
is returned and no characters are deleted. The line_length component of the 
line_editor_info_structure is updated, and the cursor_index if necessary. 
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dc 1 w i ndow_ed i tor__ut i 1 s_$de 1 ete_text_save entry 

(ptr, fixed bin, blt(1), code); 
cal 1 wi ndow_edi tor_ut I ]s_$delete_text_save 

(1 ine__ed! tor_i nfo_ptr , count, kil I_di rect ion, code); 

This entrypoint is idenentical to delete_text. but the deleted text is added to the kill 
ring. The kill_direction flag is used during kill mergng to decide whether the killed 
text will be concatenated onto the beginning or end of the current kill ring element 
"l"b is used to specify a forward kill (e.g. FORWARD_DELETE_WORD). "^O" a 
backward kill. 

del wl ndow_edI tor_ut i 1 s__$move_forward entry (ptr, fixed bin, code); 

call window_edi tor_uti ls_$move__forward (1 Ine_edi tor_info_ptr, count, code); 

Advances the cursor forward a specified number of characters (supplied by the 
variable "count") in the input line. If there are not enough characters between the 
cursor and the end of the line, error_table_$action_not_performed is returned. 

del wi ndow_edi tor_uti 1 s_$move_backward entry (ptr, fixed bin, code); 
call w I ndow_ed I tor_ut 1 1 s_$move_backward 
(1 ine_edi tor_i nfo_ptr, count, code); 

Moves the cursor backward a specified number of characters (supplied by the variable 
"count") in the input line. If there are not enough characters between the cursor and 
the end of the line, error_table_$action_not_performed is returned. 

del wl ndow_edi tor_uti 1 s_$move_f orward_word entry (ptr, code); 

call window_edI tor_utI ls_$move_forward__word (1 Ine__edi tor_I nfo_ptr, code); 

Updates the cursor_index to a position after the next word (or token) in the input 
line. A word is defined via the editor's set of token delimiters, set via the 

set_token_delimiters control order. 

dc 1 wi ndow_ed i tor__ut i 1 s_$move_backward_word entry (ptr , code) ; 
ca 11 wi ndow__ed I tor_ut i 1 s_$move__backward_word 
(1 ine_edi tor__Info__ptr, code) ; 

Updates the cursor_index to a position before the preceeding word (or token) in the 
input line. A word is defined via the editor's set of token delimiters, set via the 
set_token_delimiters control order. 

del w I ndow_ed 1 tor_ut i 1 s_$get_top_k i n_r I ng_el ement entry 

(ptr, char (*) , fixed bin 35)) 
cal 1 window_edI tor_ut I ls_$get__top__ki 1 l_r Ing__element 

(1 ine_edl tor_Info_ptr, text code). 

Returns the top kill ring element. 
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del wi nclow_edi tor_ut i 1 s_$rotate_k i 1 l_r i ng entry (ptr, fixed bin (35)) 
cal 1 window_edi tor_uti 1 s_$rotate_k 1 1 l__ring 
(1 ine_editor_info_ptr, code) 

Rotates the kill ring. 



End-Of-Window Processing 

When output has filled a window, old lines must be removed to make way for new 
ones. This is usually done by scrolling old lines off the top of the window. But for windows 
that cannot be scrolled (usually because the terminal cannot scroll) it is possible to move the 
cursor back to home, and output new lines overwriting the old ones. This is known as 
wrapped output A variation on wrapped output is to clear the window after moving the 
cursor home. The action taken when a window is full is controlled on a per-window basis by 
any one or the following more_mode modes: 

• clear the window is cleared, and output starts at the home position. 

• fold output begins at the first line and moves down the screen a line at a 
time replacing exisitng text with new text Prompts for a MORE response 
when it is about to overwrite the first line written since the last read or 
MORE break. 

• scroll lines are scrolled off the top of the window, and new lines are printed 
in the space that is cleared at the bottom of the screen. This is the default 
for all terminals capable of scrolling (i.e., those terminals that have the 
capability to insert and delete lines). 

• wrap output begins at the first line and moves down the screen a line at a 
time replacing existing text with new text Prompts for a MORE response at 
the bottom of every window of output This is the default for terminals 
incapable of scrolling. 

For more information, refer to window__io_ in Section 7. 



MORE PROCESSING 

As lines are displayed in the window, old lines are scrolled off the top of the window 
or otherwise removed. When output would cause a line to be removed that has been 
displayed since the most recent input, it is assumed that the user may not have had a chance 
to read it, and MORE processing occurs. The question "MORE?" appears on the screen, and 
no further output occurs until the user indicates that pending output is to be either displayed 
or discarded. MORE processing is controlled by the "more" mode, which is enabled by 
default 



Output resumes if the user strikes CR, and is discarded if the user strikes DEL. The 
characters used can be set by a control order. Type ahead characters are not seen by MORE 
processing. The response to MORE must be typed after the prompt appears. AH other 
characters are buffered to be returned later. 



4-10 



CP51-02 



When output is discarded, the video system simply ignores output until a get_line or 
get_chars call is made, a "resetjmore" control order call is made, or the window is cleared, 
or the cursor is moved to home. WARNING: a prompt sent just before a get_line call will 
not be printed if output is discarded, unless the prompting program first issues a 
"reset_more" control order (or otherwise resets more processing). 



OUTPUT BUFFERING 

The video system sometimes buffers output internally, sending it to the terminal when 
certain internal conditions are satisfied. All buffered output is sent to the terminal whenever 
an input call is made (e.g., window_$get_echoed_chars). This ensures that all output, including 
prompts, is seen by the user before input is read. An application program that calls window_ 
entrypoints directly should take this buffering into account to perform correctly. If it is 
necessary to send output to the terminal when no read request is to be done (e.g., displaying 
an incremental message during a long computation), the application should call window_$sync 
on the I/O switch after the output has been requested (e.g., via a call to window_$overwrite_text). 
See the description of window_$sync in the window_ subroutine description later in this 
manual. 



SUBROUTINE INTERFACE 

The video system provides .a standard set of operations for windows available through 
the window_ subroutine. Some terminals are not capable of supporting all of these operations. 
In addition, the standard iox_ operations of get_line, get_chars, and put_chars are provided. 
Some manipulations on windows are made via iox_ control orders (the window_io_ description 
in Section 7). Some of these are compatible with existing tty_ control orders. The iox_ and 
tty_ subroutines are both described in the Multics Subroutines and 110 Modules manual. 
Order No. AG93. Other manipulations control features that are specific to the window 
environment 



The iox_ operations are defined in terms of the more primitive window_ operations. 
For example, the window_ primitive, window_$overwrite_text, can only display a string of 
characters that fit on a terminal line. The iox_$put_chars wraps long strings onto multiple 
hnes, and displays control characters with the conventional octal representation. For this 
reason special care must be taken when using window_ applications on a window when iox_ 
operations are in use as well. For more details see the description of the reset_more control 
order in the window_io description in Section 7. 



COMMAND LINE INTERFACE 

The command level interface to the video system is the window_call command. This 
command can perform most of the operations on a window supported by window_ directly 
from command level The window.cail command is described in Section 5. 
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SECTION 5 
COMMANDS 



This section contains descriptions of the commands used by the menu and video 
software, presented in alphabetical order. 
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menu_create 



menu.create 



Name: menu.create 

SYNTAX AS A COMMAND 

menu_create menu_name {-control __args} 

FUNCTION 

The menu_create command creates a menu description, assigns it a specified name, and stores 
the description in a segment The menu description may be used witli other menu commands, 
active functions, and subroutines. 

ARGUMENTS 

menu_name 

is the name assigned to the menu when it is stored. 

CONTROL ARGUMENTS 

-pathname PATH, -pn PATH 

is the pathname of the segment in which the menu is stored. Menus are stored in value 
segments. If the specified segment does not exist, the user is asked argument). The value 
suffix is assumed. If this control argument is omitted, the user's default value segment 
(>udd>Project_id>Person_id>Person_id.value) is used to store the menu. 

-brief, -bf 

means that if the segment specified by the -pathname control argument does not exist, it 
is to be created without querying the user. 

-option STR, -opt STR 

specifies a menu option. The options appear in the menu in the order given. At least 
one option must be supplied. If STR contains blanks or special characters, it must be 
quoted. 

-header STR, -he STR 

specifies a line of header. All header lines specified appear in the menu in the order 
given. If STR contains blanks or special characters, it must be quoted. 

-trailer STR, -tr STR 

specifies a trailer line. All trailers appear in the menu in the order given. If STR 
contains blanks or special characters, it must be quoted. 

The remaining control arguments control the format of the menu. All are optional, 
-columns N, -col N 

where N is a positive decimal integer, sets the number of columns in the menu to N. 
The default is one column. 

-center_headers, -ceh 

causes all header lines to be centered. 
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menu create menu_crealje 



-no__center_headers, -nceh 

causes header lines to be flush left This is the default 

-center„trailers, -cet 

causes all trailer lines to be centered. 

-no__center_trailers, -ncet 

causes trailer lines to be flush left This is the default 

-option_keys STR, -okeys STR 

specifies the keystrokes to be associated with each option. Each character in STR is 
associated with the corresponding option, so that if it is typed, the corresponding option 
is selected. There must be at least as many characters in STR as there are options. If 
this control argument is not given, the string 

"123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ" is used. 

-pad C 

where C is one character, specifies the padding character for centering. The default is 
the space character. 

-linejength N, -11 N 

where N is a positive decimal integer, specifies the line length for the menu. If not 
supplied, the line lengtti will be the line l^gth of the user's terminal at the time the 
^ command is invoked. 

ACCESS REQUIRED 

The user must have r and w access on the value segment 
EXAMPLES 

The following example sets up a small menu named compile. 

menu_create compile -pn [pd]>temp -pad = -he "SAMPLE MENU" -tr = -ceh -cet 
-columns 2-11 78 -opt "Compile with No Options" 
-opt "Symbol Table" -opt "Profile Info" 

Creates a menu that looks like this: 

(1) Compile with No Options (3) Profile Info 

(2) Symbol Table 
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menu.delete 



menu.delete 



Name: menu_delete 

SYNTAX AS A COMMAND 

menu_delete inenu_name {-control_arg} 

FUNCTION 

The menu.delete command deletes a menu description from a specified value segment 

ARGUMENTS 

menu_name 

is the name that was assigned to the menu when it was stored. 

CONTROL ARGUMENTS 

-pathname PATH, -pn PATH 

is the pathname of the value segment in which the menu is stored. If this control 
argument is not given, the user's default value segment is searched for the menu. The 
value suffix is assumed. 
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menu describe 



menu_describe 



Name: menu^describe 

SYNTAX AS A COMMAND 

nienu_descr ibe menu__name {-cohtrol_args} 

SYNTAX AS AN ACT/VE FUNCTION 

[menu_descr ibe menu_name -control_args] 

FUNCTION 

The menu.describe command prints or returns information about a menu. 

ARGUMENTS 

menu.name 

is the name that was assigned to the menu when it was stored. 

CONTROL ARGUMENTS 
-count, -ct 

returns the number of options defined in the menu, 
-height 

returns the height of the menu. 

-pathname PATH, -pn PATH 

is the name of the value s^ment in which the menu has been stored. The value suffix 
is assumed. If this control argument is omitted, the user's default value segment is 
searched for the menu. 

-width 

returns the width of the menu. 
NOTES 

When used as an active function, exactly one of -count, -height, or -width must be given. 
As a command, any number are allowed. If none are given, all attributes are displayed. 
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menu_display 



menu_display 



Name: menu display 

SYNTAX AS A COMMAND 

menu_di splay menu__name {-control _args} 

FUNCT/ON 

The menu_display command displays a menu in a window. 

ARGUMENTS 

menu_name 

is the name that was assigned to the menu when it was stored. 

CONTROL ARGUMENTS 

-io_switch STR. -is STR 

specifies the name of an I/O switch for a window. The default is user_outpuL 

-pathname PATH, -pn PATH 

is the name of the value segment in which the menu has been stored. The value suffix 
is assumed. If this control argument is omitted, the user's default value segment is 
searched for the menu. 
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menu_get_choice 



menu_get_choice 



Name: menu get choice 

SYNTAX AS A COMMAND 

menu_get_choice menu__name {-control_args} 

SYNTAX AS AN ACTIVE FUNCTION 

[menu_get__choice menu__name {-control_args}] 

FUNCTION 

The menu_get_choice command, given the menu called menu_name on display in a window, 
gets a menu choice from the user and prints or returns it. 

ARGUMENTS 

menu_name 

is the name that was assigned to the menu when it was stored. 

CONTROL ARGUMENTS 

-pathname PATH, -pn PATH 

is the name of the value segment in which the menu has been stored. The value suffix 
is assumed. If this control argument is omitted, the user's default value segment is 
searched for the menu. 

-io_switch STR, -is STR 

where STR is the name of an I/O switch for a window. The default is user_i/o. 

-default_fkeys STR, -fkeys STR 

specifies the keys to be used if the terminal does not have function keys or if the 
terminal does not have the proper set of function keys. See "Notes on Function Keys" 
below. 

-function_keys STR, -fkeys STR 

specifies the keys to be used to simulate function keys. This control overrides any 
function key definitions already established for the terminal. See "Notes on Function 
Keys" below. 
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menu__gel_choice 



menu_get_choice 



NOTES ON FUNCTION KEYS 

Many terminals have function keys. On many of these terminals (such as the Honeywell 
VIP7801) they are labelled "Fl", "F2", etc. If you type one of these function keys, 
menu_get_choice returns the string "F*", where * is a one or two digit number signifying 
which function key was pressed. It is possible to specify your own set of keystrokes to be 
used in lieu of the terminal's function keys, or to specify a set of keystrokes to be used if 
the terminal does not have enough function keys. These are done by using the -fkeys and 
-dfkeys control arguments. Each of these control arguments is followed by a string. Each 
character in this string is used to simulate a function key. The first character is used to 
simulate function key 0, the next to simulate function key 1, etc. To simulate a given 
function key, type esc-C, where C is the character corresponding to the function key. Thus 
if the string is "0123456789", typing esc-2 will return F2. 

The -fkeys control argument is used to specify keystrokes to be used instead of any which 
might be defined for the terminal. If this control argument is given, then the simulation of 
function keys always takes place. 

The -dfkeys control argument is used if you want to use the terminal defined function keys 

if possible, but wish to specify key sequences to be used to simulate function keys if 
necessary. Each character in the string following -dfkeys corresponds to one function key. If 
the character is a space, it means it makes no difference if the terminal has a function key 
corresponding to that position. If the character is not a space, that character will be used to 
simulate a function key if necessary. If the terminal does not have a function key for every 
non-space character in the string, then the -dfkeys string is used to simulate function keys. 
Thus, the string ?p q" means that you do not care whether the terminal has a function 
key 0 or a function key 3, but you wish to use function keys 1,2, and 4. If any of these 3 
function keys is not present on the terminal, then esc-? will substitute for Fl, esc-p will 
substitute for F2, and esc-q will substitute for F4. 
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menu_list 



meau.list 



Name: menu^Iist 

SYNTAX AS A COMMAND 

menu_Tist {menu_s tar name} {-control_arg} 

SYNTAX AS AN ACTIVE FUNCTION 

Cmenu_list {menu_s tar name} {-control_arg}] 

FUNCTION 

The menu.list command lists the names of the menu descriptions stored in a value segment 

ARGUMENTS 

menu_stamame 

is a starname that is used to search for menu descriptions. If it is omitted, the default 
is **. 

CONTROL ARGUMENTS 

-pathname PATH, -pn PATH 

is the pathname of the value segment in which the menu has been storett The value 
suffix is assumed. If this control argument is not given, the user's default value segment 
(udd>Project_id>Person_id>Person_id. value) is searched for the menu. 
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window call 



window call 



Name: window^call 

SYNTAX AS A COMMAND 

window_call arguments {-control_args} 

SYNTAX AS AN ACT/VE FUNCTION 

[window_call arguments {-control__args}] 

FUNCTION 

The window.call command provides a command interface to the video system. 
ARGUMENTS 

are listed below. A detailed description follows the control arguments section. 



bel 1 

change_wi ndow, chgwd 
clear_region, cl rgn 
c]ear_to_end__of_l i ne, cleol 
c 1 ear_to_end_of _w i ndow , c 1 eowd 
clear_window, clwd 
c r eat e_wi ndow, crwd 
de1ete_chars, dlch 
delete_wi ndow, dlwd 
get_echoed_chars, gech 
get_f i rst_l i ne, gfl 
get_one_unechoed__char , gouch 
get_posi tion, gpos 



get__termi nal_hei ght, gtmhgt 
get_termi nal_width, gtmwid 
get_unechoed_chars , guch 
get_wi ndow_hei ght, gwdhgt 
insert_text, itx 
i nvoke 

overwr i te_text , otx 
revoke 

scrol l_reg i on, scrgn 
set_pos i t ion, spos 
set__posi tion_rel , sposrel 
suppor ted__term i na 1 
sync 

video_i nvoked 

wr i te_sync__read , wsr 



CONTROL ARGUMENTS 
-column C, -col C 

specifies a column on the screen. The leftmost column is 1. If -column is not specified, 
the default is the remainder of the screen. 

-count N, -ct N 

specifies a count See the specific requests for details. 

-height NL, -hgt NL 

specifies the height of a region or a window for a request If -height is not specified, 
the default is the remainder of the screen. 
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window_call 



window_call 



-io^switch WINDOW, -is WINDOW 

where WINDOW is an I/O switch. The operation is performed on the window associated 
with the named I/O switch. 

-line L 

specifies a line on the screen. The top line is line 1. 
-line_speed N, -Is N 

specifies the speed of the terminal's connection to Multics. N is in characters per 
second. 

-terminal_type STR, -ttp STR 

where STR is a terminal type. Information on accepted terminal types can be obtained 
with the print_terminal_types (ptt) conmiand. 

-string TEXT, -str TEXT 

specifies a text string for display. If TEXT contains blanks or other special command 
processor characters it must be enclosed in quotes. 

-width NC, -wid NC 

specifies the width of a region for a request If -width is not specified, the default is 
the remamder of the screen. 



Argument Descriptions 



bell 

SYNTAX AS A COMMAND 

wdc bell {-io_switch WINDOW} 

FUNCTION 

activates the terminal bell. On some terminals, this may produce a visual indication instead of 
an audible tone. The cursor position must be defined. The cursor is positioned to the current 
position of the specified window, if it is elsewhere on the screen. If -io_switch is not 
specified, user_i/o is assumed. 
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window_call 



window_call 



change window, chgwd 

SYNTAX AS A COMMAND 

wdc chgwd {-line L} {-column C} {-height NL} {-width NC} 
{-io_switch WINDOW} 

FUNCTION 

changes the origin or size of the specified window. At least one of -line, -column, -height, 
or -width is required, -line L specifies the line number or the screen where the window is 
to begin. If -line is not supplied, the default is column 1. If only the -line control 
argument is given (changing the top line of the window), the window length is automatically 
adjusted. That is, if the -line control argument increases the value of the top line number 
(moving the window down), the window length shrinks accordingly. However, if the -line 
control argument decreases the top line number (moving the window up), the length remains 
the same, -column C specifies the column number on the screen where the window is to 
begin. If -column is not supplied, the default is column 1. If only the -column control 
argument is given (changing the first column on the left), the window width is automatically 
adjusted, -height NL specifies the height of the window. If height is not specified, the 
default is the remainder of the screen. If only the -height control argument is given 
(changing the window length), the origin line remains the same, -width NC specifies the 
width of the window. If width is not specified, the default is the remainder of the screen. 
If only the -width control argument is given (changing the window width), the origin column 
remains the same. If -io_switch is not specified, user_i/o is assumed. See Section 2 for 
more information on the use of this command. 



clear region, clrgp 

SYNTAX AS A COMMAND 

wdc clrgn -line N -column N -height N -width N {-io_switch WINDOW} 
FUNCT/ON 

clears the specified rectangular region of the window to blanks. The region may be part or 
all of the window. If -io_switch is not specified, user_i/o is assumed. See Section 2 for 
more information on the use of this command. 



clear to end__of__line, cleol 

SYNTAX AS A COMMAND 
I wdc cleol {-io_switch WINDOW} 
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wmdow_call 



wmdow_call 



FUNCTION 

clears the line from the current cursor position to the end of the line to blanks. The current 
cursor position must be defined. If -io.switch is not specified, user_i/o is assumed. 



clear__to_end__of__wmdow, cleowd 

SYNTAX AS A COMMAND 

wdc cleowd {-io__switch WINDOW} 

FUNCTION 

clears the window from the current cursor position to the end of the window to blanks. The 
current cursor position must be defined. If -io_switch is not specified, user_i/o is assumed. 



clear window, clwd 

SYNTAX AS A COMMAND 

wdc clwd {-io_switch WINDOW} 

FUNCTION 

clears the specified window so that its content becomes entirely blank. The current cursor 
position is defined to be at Line 1, Column 1 of the specified window. If -io_switch is not 
specified, user_i/o is assumed. See Section 2 for more information on the use of this 
command. 



create window, crwd 

SYNTAX AS A COMMAND 

wdc crwd -io_switch WINDOW {-line L -column C -height NL -width NC} 
FUNCTION 

creates a new window on the screen with name (and I/O switch) WINDOW, -line L specifies 
the line number on the screen where the window is to begin. If -line is not supplied, the 
default is line 1. -column C specifies the column number on the screen where the window is 
to begin. If -column is not supplied, the default is column 1 -height NL specifies the height 
of the window. If -height is not specified, the default is the remainder of the screen, 
-width NC specifies the width of the window. If -width is not specified, the default is the 
remainder of the screen. The window is blank when created, and the cursor position is Line 
1, Column 1 of the new window. See Section 2 for more information on the use of this 
command. 
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window_call 



window_call 



delete ^chars, dich 

SYNTAX AS A COMMAND 
I wdc dich -count N {-io_switch WINDOW} 
FUNCTION 

deletes N characters to the right of the current cursor position on the current line. The 
cursor remains stationary; characters to the right of the deleted characters move to the left to 
fill the vacated space. The current cursor position must be defined. If -io_switch is not 
specified, user_i/o is assumed. 



delete__window, dlwd 
SYNTAX AS A COMMAND 
i wdc dlwd -io_switch WINDOW 
FUNCTION 

destroys the specified window. The I/O switch is closed and detached. See Section. 2 for 
more information on the use of this command. 



get_echoed_chars, gech 

SYNTAX AS A COMMAND 

wdc gech -count N {-io_switch WINDOW} 

FUNCTION 

reads characters from the terminal until either N characters or a break character is read. All 
characters except the break are echoed on the screen in the current window. For information 
on break characters, see the break_table control order in the description of window_io_ in 
Section 7. Tne current cursor position must be defined. If -io_switch is not specified, 
user_i/o is assumed. 
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window_call 



window_call 



ACTiyE FUNCTION USAGE 

two strings are returned. The first contains any nonbreak characters read, and the second 
contains the break character, if any. 

get__f irst__line, gfl 
SYNTAX AS A COMMAND 
wdc gfl {-io^switch WINDOW} 
FUNCTION 

prints the line on the screen where the specified window begins. If -io_switch is not 
specified, user_i/o is assumed. 

ACTIVE FUNCTION USAGE 

returns the line on the screen where the specified window begins. If -io_swilch is not 
specified, user_i/o is assumed. 

get_one__imechoed_char, gouch 

SYNTAX AS A COMMAND 

wdc gouch {-io_switch WINDOW} 

FUNCTION 

reads a single unechoed character from the terminal. If -io__switch is not specified, user_i/o 
is assumed. 

ACTIVE FUNCTION USAGE 

returns a single unechoed character from the terminal. 

get_position, gpos 

SYNTAX AS A COMMAND 

wdc gpos {-Io_switch WINDOW} 

FUNCTION 

prints the current line and column position of the cursor. 
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window_call 



window_call 



ACJiyE FUNCTION USAGE 

returns the line and column position as a pair of integers separated by a space. If -io.switch 
is not specified, user_i/o is assumed. 

get^terminal height, gtmhgt 

SYNTAX AS A COMMAND 

wdc gtmhgt 

FUNCTION 

prints the total number of lines on the user's terminal. 
ACTIVE FUNCTION USAGE 

returns the total number of lines on the user's terminal. 

get ^terminal width, gtmwid 

SYNTAX AS A COMMAND 

wdc gtmwid 

FUNCTION 

prints the total number of columns on the user's terminal. 
ACTIVE FUNCTION USAGE 

returns the total number of columns on the user's terminal. 

get_imechoed__chars, guch 

SYNTAX AS A COMMAND 

wdc guch -count N {-io_switch WINDOW} 

FUNCTION 

reads characters from the terminal until either N characters or a break character are read. 
The current cursor position must be defined. If -io_switch is not specified, user_i/o is 
assumed. 
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wmdow_call window_call 



ACTIVE FUNCTION USAGE 

returns two strings. The first contains any nonbreak characters read, and the second contauis 
the break character, if any. 

get_wiiidow_Jieight, gwdhgt 

SYNTAX AS A COMMAND 

wdc gwdhgt {-io_switch WINDOW} 

FUNCTION 

prints the height of the specified window. 



insert^text, itx 

SYNTAX AS A COMMAND 

wdc itx -string window {-io__switch WINDOW} 
FUNCTION 



I 



displays the text string window at the current cursor position. If there are any characters to 
the right of the current position on the current line, they are moved to the right to 
accommodate the new string. There is no wraparound feature; if text goes off the screen it 
is dropped. The text string window may contain only printable ASCII characters. Use the | 
io.call put.chars command to display nonprintable characters in a readable form. If 
-io_switch is not specified, user_i/o is assumed. 



invoke 

SYNTAX AS A COMMAND 

wdc invoke {-line_speed N, -Is N} 

FUNCTION 

activates the video system on the user's terminal. If no line speed is specified, the current { 
line speed is used. The user's terminal must be attached witii the tty_ I/O module. If | 
graphics or auditing are in use they must be removed before this conmiand is given. The 
settings of the following tty_ modes are copied when the video system is invoked: vertsp,- 
can, erkl, esc, red, and ctl_char. In addition, if '^pl is set on video system invocation, -^more 
will be set in the video system. (For more details on modes, see the window_io_ I/O 
module in Section 7.) Similarly, the settings of the current erase and kill characters are 
copied when the video system invoked. (See "Real-Time Editing" in Section 4 for details.) 
See Section 2 for more information on the use of this command. 
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windowMll 



window.call 



overwrite__text, otx 

SYNTAX AS A COMMAND 

wdc otx -string STR {-io_switch STR} 

FUNCTION 

displays the text string STR at the current cursor position in the window. If there is any 
text to the right of the current position in the window, it is overwritten with the supplied 
string. The text string STR may contain only printable ASCII characters. Use the io_call 
put.chars command to display nonprintable characters in a readable form. If -io.switch is 
not specified, user_i/o is assumed. 



revoke 

SYNTAX AS! A COMMAND 
wdc revoke 

FUNCTfON 

removes the video system from the user's terminal. The standard tty_ attachment is restored. 
The settings of the following modes are copied when the video system is revoked: vertsp, 
can, erkl, esc, red, and ctl_char. If '^more is set while in the video system, '^pl mode will 
be set after revoking the video system. (For more details on modes, see the window_io_ I/O 
module in Section 7.) Similarly, the settings of the current erase and kill characters are 
copied when the video system is revoked. (See "Real-Time Editing" in Section 4 for details.) 
See Section 2 for more information on the use of this command. 



scroll region, scrgn 

SYNTAX AS A COMMAND 
I wdc scrgn -count N {-line L -height C -io_switch WINDOW} 
FUNCTION 

scrolls the specified region N lines as specified by -count. The specified region is the whole 
width of the screen. It can be a whole window or part of a window. If -count N is 
negative the window is scrolled down, and if it is positive the window is scrolled up. If lin^ 
are scrolled off the screen they are dropped. If -line is not supplied, the default is 1. If 
-height is not supplied, the remainder of the window is scrolled. If -io_switch is not 
specified, user_i/o is assumed. 
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set^position, spos 
SYNTAX AS A COMMAND 

wdc spos -line L -column C {-io_switch WINDOW} 
FUNCTION 

positions the cursor to the specified line and column of the specific window. If -io_switch is 
not specified, user_i/o is assumed. 

set__position rel, sposrel 

SYNTAX AS A COMMAND 

wdc sposrel -line L -column C {-io_switch WINDOW} 
FUNCTION 

changes the cursor position by N lines and N columns. If -io_switch is not specified, 
user_i/o is assumed. The current cursor position must be defined. One of the control_args 
must be specified and botii may be specified. Whichever control_arg is not specified defaults 
to zero. 

supported ^terminal 

SYNTAX AS A COMMAND 

wdc supported_termi nal {-ttp terminal_type} 
FUNCTION 

returns "true" if the video system can be invoked on the specified terminal type. If no 
terminal type is specified, the current terminal type is used. 

sync 

SYNTAX AS A COMMAND 
wdc sync {-io_swltch WINDOW} 
FUNCTION 

waits for the last operation performed on the window to be completed. Over certain 
networks it may not be possible to actually wait for delivery of the characters to the 
terminals. If -io_switch is not specified, user_i/o is assumed. 
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video invoked 

SYNTAX AS A COMMAND 
wdc video_i nvoked 
FUNCTION 

returns "true" if the video system is in use in the user's process. 

write ^sync__read, wsr 

SYNTAX AS A COMMAND 
I wdc wsr -string STR -count N {-io_switch WINDOW} 
FUNCTION 

displays a prompting string STR at the current cursor position in the window, and then reads 
input typed in response to the prompt Characters are read unechoed, until either N 
characters or a break character is r^. If -io_switch is not specified, user_i/o is assumed. 

ACTIVE FUNCTION USAGE 

prints a prompting string and returns the characters read. 
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SECTION 6 
PL/I SUBROUTINE INTERFACE 



This section contains descriptions of the PL/I subroutines used by the menu and video 
software, presented in alphabetical order. 



6-1 



CP51-02 



menu_ 



menu_ 



Name: menu^ 

The menu, subroutine provides menu display and selection services. It can display a menu in 
a window and get a selection from the user. The entries work with menu objects. A menu 
object is a pointer to an internal description of a menu. The caller is expected to preserve 
the pointer, and to perform no operation on it other than comparison with the null pointer 
or with another menu object, except through the menu_ subroutine. £>eclarations for the 
entries and the associated structures are in the include file menu_dcls.incl.pll described below 
in "Data Structures". 



Entry: meniL-$create 

This entry creates a menu object given its description. The menu data structure is allocated 
in a caller supplied area, and may be saved across processes by calling menu_$store. A 
pointer to the new menu is returned, also with the minimum size of a window to hold the 
menu. 

USAGE 

declare menu_$create entry ((*) char (*) varying, (*) char (*) varying, 
(*) char (*) varying, ptr, (*) char (1) unal, ptr, ptr, ptr, 
fixed bin (35)) ; 

call inenu_$create (choices, headers, trailers, format_ptr, keys, area_ptr, 
needs_ptr, menu, code); 

ARGUMENTS 
choices 

is an array of the names of the options. (Input)* If the maximum number of choices is 
exceeded, the code menu_et_$too_many_options is returned. The current maximum is 61. 

headers 

is an array of headers. (Input) If the length of the first header is zero, then no headers 
are used. This allows the caller to specify no headers, without resorting to a zero-extent 
array, which is invalid PL/ 1. 

trailers 

is an array of trailers. (Input) As for headers, a zero-length first trailer means that no 
trailers are displayed. 

format_ptr 

points to a structure, menu_format, that controls formatting of the menu. (Input) This 
structure is described below in "Data Structures". 
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keys 

is an array specifying the keystroke for each option. (Input) The array must have at 
least as many elements as the array of option names. If not, the error code 
menu_et_$too_few_keys is returned. It may have more keys than choices. Each item of 
the array must be unique, or menu_et_$keys_not_unique is returned. If the valid keys 
(the keys for which there are choices) are either all upper case or all lower case, 
menu_$get_choice will treat upper and lower case letters identically. 

area_ptr 

is a pointer to an area where the menu description is allocated. (Input) If the area is 
not large enough, the area condition is signalled. If this pointer is null, the system free 
area is used. 

needs_ptr 

points to the menu_requirements stnicture giving requirements to display the menu. 
(Input) The structure is described below in "Data Structures". The caller supplies this 
structure and fills in the version number menu_requirements_version_l, the remaining 
members are output from this entry. 

menu 

is a newly created menu object (Output) 

code 

is a standard system error code, or an error code from menu_et_. (Output) 



Entry: menu_$delete 

This entry deletes a menu object from a specified value s^ment 
USAGE 

declare menu_$delete entry (char (*) , char (*) , char {*) ^ fixed bin (35)); 

call menu_$de1ete (dirname, entryname, menu_name, code); 

ARGUMENTS 

dirname 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the segment (Input) it must have the value suffix, 
menu.name 

is the name that was assigned to the menu when it was stored (see the description of 
menu_$store). (Input) 

code 

is a standard system error code. (Output) 
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Entry: menii^$describe 

This entry fills in a caller-supplied data structure describing some of the aspects of a menu 
object Ilie caller can use this to ensure a window is sufficiently large to hold a menu. 

USAGE 

declare menu_$descr ibe entry (ptr, ptr, fixed bin (35))* 
call menu_$descr ibe (menu, needs_ptr, code); 
ARGUMENTS 
menu 

is the menu object to describe. (Input) 
needs_ptT 

points to a structure declared like menu_requirements described in "Data Structures" 
below. (Input) The caller fills in the version to be menu_requirements_version_l, and the 
remaining members are filled in by this entry. 

code 

is a standard system error code. (Output) 



Entry: menu__$destroy 

This entry is used to delete a menu object The caller uses this to free storage of a menu, 
since the representation of a menu is not known outside the menu_ subroutine. This entry 
has no effect on screen contents or on stored menus. 

USAGE 

declare menu_$destroy entry (ptr, fixed bin (35) )» 

call menu_$destroy (menu, code); 

ARGUMENTS 

menu 

is the menu object to destroy. (Input) 

code 

is a standard system error code. (Output) 
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Entry: menu^Sdisplay 

This entry displays a menu object on a supplied window. 
USAGE 

declare menu_$di splay entry (ptr, ptr, fixed bin (35)) » 

call menu_$di splay (window, menu, code); 

ARGUMENTS 

window 

is a pointer to an lOCB for an I/O switch attached through window_io_. (Input) This 
window must be large enough to hold the menu. A menu window should be us^ ONLY 
for menu I/O, if redisplay optimizations are desired. 

menu 

is the menu object to be displayed. (Input) 

code 

is a standard system error code. (Output) 



Entryr menu__$get_choice 

This entry returns a choice from a menu. The menu is assumed to be already displayed in 
the window. 

USAGE 

declare menu $get_choice entry (ptr, ptr, ptr, bit (1) aligned, fixed bin, 
fixed bin (35)) ; 

call menu_$get_choice (window, menu, function_key_info, fitey, selection, 
code) ; 

ARGUMENTS 

window 

is a pointer to the lOCB for the I/O switch used to display the menu. (Input) 
menu 

is the menu object on display in the window. (Input) 
f unction_key_inf o 

is a pointer to a data structure describing the function keys available on the terminal. 
(Input) This data structure is obtained by the caller from the ttt_info_$function_key_data 
subroutine. If this pointer is null, no function keys are used. 
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fkey 

returns a value of "l"b if a function key was hit instead of a menu selection. (Output) 
selection 

gives the option number or function key number chosen by the user. For an option, it 
is a number between 1 and the highest defined option, inclusive. For a function key, it 
is the number of the function key. 

code 

is a standard system error code. (Output) 
NOTES 

If a terminal has no function keys, the caller can define input escape sequences for function 
keys. These may be chosen to have mnemonic value to the end user. For example, if 
Function Key 1 is used to print a help file, the input sequence ESC h could replace it In 
some applications, this will be easier for the end user to remember than an unlabelled 
function key. The caller can define these keys by allocating and filling in the same function 
key structure normally returned by the ttt_info_ subroutine. 

If a key is hit that is not one of the option keys and is not a function key, then the 
terminal bell is rung. 



Entry: menu^$list 

This entry lists the menu objects stored in a specified value segment 
USAGE 

declare menu_$list entry (char (*) , char (*) , char (*) , ptr, fixed bin, ptr, 
fixed bin (35)) ; 

call menu__$list (dirname, entryname, menu__s tar name, area_ptr, 
menu_l ist__info_version, menu_l i st__i nfo_ptr , code); 

ARGUMENTS 

dirname 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the segment (Input) It must have the value suffix. 
menu_starname 

is matched against the names of the menus stored in the segment (Input) Only names 
that match menu.stamame are returned, (see the description of menu_$store). 

area_ptr 

is a pointer to an area in which to allocate the structure containing the menu names. 
(Input) If it is null, the system free area is used. 
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menu_list_inf o_version 

is the version of the menu_!ist_info structure that the caller expects. (Input) It must be 
a supported menu_list_info structure version. The only supported version is 
menu_list_inf o_version_l. 

menu_list_inf o_ptr 

is a pointer to the menu_list_info structure, described below under "Data Structures". 
(Output) 

code 

is a standard system error code. (Output) 



Entry: menu ^Sretrieve 

This entry retrieves a menu from a specified segment The segment must be a value segment 
The menu data structure is allocated in a caller-supplied area. The menu information is 
copied from the menu object stored in the segment into the newly allocated structure. 

USAGE 

declare menu__$retr i eve entry (char (*) , char (*) , char {>») , ptr, ptr, 
f i xed b i n (35) ) ; 

call menu_$retr i eve (dirname, entryname, menu__name, area__ptr, menu_ptr, code); 

ARGUMENTS 

dimame 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the segment (Input) It must have the value suffix. 
menu_name 

is the name that was assigned to the menu when it was stored (see the description of 
menu_$store). (Input) 

area_ptr 

is a pointer to an area where the menu object is allocated. (Input) If this argument is 
null, the system free area is used. If the area is not large enough, the area condition is 
signalled. 

menu_ptr 

is a pointer to the menu object that is retrieved from the segment (Output) 

code 

is a standard system error code. (Output) 
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Entry: menu ^Sstore 

This entry stores a menu object in a specified segment The specified segment must be a 
value segment 

USAGE 

declare menu_$store entry (char {*) , char (*) , char (*) , bit(l) aligned, ptr, 
fixed bin (35)) ; 

call menu__$store (dirname, entryname, menu_name, create__sw, menu_ptr, code); 

ARGUMENTS 

dirname 

is the pathname of the containing directory. (Input) 
entryname 

is the entryname of the segment (Input) It must have the value suffix. 
menu_name 

is a name to be assigned to the menu. (Input) 

create_sw 

determines whether or not the segment is created if it does not already exist If the 
s^ment does not exist a value of "I'^b will cause it to be created. (Input) 

menu_ptr 

is a pointer to the menu object that is to be stored in the segment (Input) 

code 

is a standard system error code. (Output) 
DATA STRUCTURES 

A menu is described by the "menu_format" structure. It is declared in menu_dcls.incl.pll. 

del 1 menu_f ormat aligned based (menu__format_ptr) , 

2 version fixed bin, 
2 constraints, 

3 max_width fixed bin, 

3 max_height fixed bin, 

2 n^columns fixed bin, 
2 flags, 

3 center_headers bit (1) unal, 

3 center_trai lers bit (1) unal, 

3 pad bit (3M unal , 

2 pad__char char (1) ; 
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STRUCTURE ELEMENTS 



menu_format 

specifies the format for menu display. (Input) It gives limits for number of lines and 
characters per line, specifies the number of columns (of options), and controls centering 
of headers and trailers. 

version 

must be menu_format_version_l. (Input) 
max_width 

is the width of the window the menu will be displayed on. (Input) This value is used 
for centering headers and aligning colunms. 

max_height 

is the maximum height of the window, in lines. (Input) 
n_columns 

is the number of columns to use in displaying options. (Input) 
centeT_headers 

if set, header lines will be catered usang tiie window width supplied above. (Input) If 
not set, they are flush with the left edge of the window. 

center_trailers 

same as center_headers, but for trailers. (Input) 

pad 

must be "0"b. (Input) 
pad_char 

is the character used for centering headers and/or trailers. (Input) 
THE MENU_LISTJNFO STRUCTURE 

This entry returns information in the menu_list_info structure, found in the include file 
menu_list_info.incl.pll, shown below: 

del 1 menu_l i st__i nf o aligned based (menu_l i st_i nf o_ptr) , 

2 version fixed bin, 

2 n_names fixed bin, 

2 name_str i ng__length fixed bin (21), 
2 names (menu_n st_n_names refer 

(menu__l i st_i nfo.n_names) ) al igned, 
3 position fixed bin (21), 

3 length fixed bin (21), 

2 name_string character (menu_l i st_name__str i ng_length 

refer (menu_l i st_i nfo.name_str i ng_length) ) 
unal igned; 
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STRUCTURE ELEMENTS 



version 

is the version of this structure, menu_list_info_version_l. (Output) 
n_names 

is the number of menu object names that matched the supplied starname. (Output) 

name_strin&_length 

is the total length of all the names that matched the supplied starname, concatenated 
together. (Output) 

names 

is an array of information with one entry for each name that matched the specified 
starname. (Output) 

position 

is the position in the string menu_list_info.name_string of this menu name. (Output) 

length 

is the length of this menu name in the string menu_list_info.name_string. (Output) 
name_string 

contains all the returned names, concatenated together. (Output) The PL/ 1 "defined" 
attribute can be used to advantage to refer to individual names. For example, we wish to 
print the menu name indexed by name_index. 

begi n; 

declare this__name character (menu_] i st__i nf o. 1 ength (name_i ndex) ) 
def i ned (menu_l i st_i nfo.name_str i ng) 
position (menu_l ist_inf epos i t ion (name_i ndex) ) ; 

call ioa_ ("The '^d'th menu name is: '^a", name_index, this__name); 

end; 
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THE MENU_REQUIREMENTS STRUCTURE 

The requirements for a menu are specified by the menu_requirements structure. It is declared 
in menu_dcls.incl.pll. 

del 1 menu_requi rements 
2 version 
2 1 i nes_needed 
2 width_needed 
2 n__options 



STRUCTURE ELEMENTS 



version 

is set by the caller, and must be menu_requirements_version_l. (Input) 
lines_needed 

is the number of lines required. (Output) If the window does not have this number of 
lines, menu display will fail. 

width_needed 

is the number of columns needed. (Output) 

n_options 

is the number of options defined. (Output) 

The include file, menu_dcls.incl.pll, also provides an array of key characters that may be 
used in the menu to select options. This array can be used by ttie caller as input to the 
menu_$create entry. Its name is MENU_OPTION_KEYS. 



aligned based (menu_requi renients__ptr) , 
fixed bin, 
fixed bin, 
fixed bin, 
fixed bin; 
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Name: video__data__ 

The video_data_ subroutine is a data segment containing information about the video system. 
Entry: video ^data ^$tenninal^iocb 

This is the terminal control switch lOCB pointer. If the video system is activated for the 
user's terminal, this pointer is nonnull, and points to the lOCB for the switch user_terminal_. 

USAGE 

fnt typ declare video_data_$terminal_iocb pointer external static; 
NOTES 

User programs may use this pointer for two purposes: 

1. Inquiring as to whether the video system is activated, by checking to see if the pointer 
is null. 

2. Determining the physical characteristics and capabilities of the terminal. This may be 
accomplished with the get_capabilities control order, described under the window_io_ I/O 
module. The height and width returned will be that of the physical terminal screen. 

No other manipulations of this switch are permitted. 
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Name: video__utiIs_ 

This subroutme provides interfaces for activating and de-activating the video system. 



Entry: video__utils__$turn_on__login__channel 

This entry removes the existing attachment of the user's terminal, replacing it with the video 
system. When this entry returns successfully, the switch user_terminal_ is attached through 
tc_io_ to the user's terminal. The switch user_ i/o is attached through window_io_ to a 
window covering the entire screen, invoked: vertsp, can, erkl, esc, red, and ctl_char. In 
addition, if ^pl is set on video system invocation, '^more will be set in the video system. 
(For more details on modes, see the window_io_ I/O module.) Similarly, the settings of the 
current erase and kill characters are copied when the video system is invoked. (See 
"Real-Time Editing" for details.) To see how the standard I/O switch attachments change 
when you activate the video system on your terminal, refer to Figure A-2 in Appendix A. 

USAGE 

declare video_uti ls_$turn_on_login_channel entry (fixed bin (35) » char (*)); 

call video_ut i 1 s_$turn_on_logi n_channel (code, reason); 

ARGUMENTS 

code 

is a standard system error code. (Output) 
reason 

contains information about the error, if there is one. (Output) (128 characters are enough 
to hold any message that may be returned in reason!) 

NOTES 

If the video system is already in service on the user's terminal, the status code 
video_et_$wsys_invoked is returned, and the value of reason is not defined. 

If the activation of the video system fails, the original attachment of the terminal (through 
tty_) is restored, and information is returned in reason and code. 

In particular, if the switch user_i/o is not currently attached through tty_, the code 
video_et_$switch_not_attached_with_tty_ is returned. This may indicate that the user has 

remove graphics or auditing and try again. 
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Entrjr: video_utils_$tuni_off_Jogin_chaimel 

This entry reverses the actions of video_utils_$turn_on_login_channel. That is, it removes the 
window attachment of user_i/o, detaches terminal control from the user's terminal, and 
attaches user_i/o to the user's terminal via tty_. The settings of the following modes are 
copied when when the video system is revoked: vertsp, can, erkl, esc, red, and ctl_char. If 
'^more is set while in the video system, '^pl mode will be set after revoking the video system. 
(For more details on modes, see the window_io_ I/O module.) Similarly, the settings of the 
current erase and kill characters are copied when the video system is revoked. (See 
"Real-Time Editing" for details.) It is the user's responsibihty to detach any windows other 
than user_io before calling this entry point 

USAGE 

declare video_uti ls__$turn_of f_logi n_channel entry (fixed bin (35) ) » 

call video_uti ls_$turn_of f_login__channel (code); 

ARGUMENTS 

code 

is a standard system error code. (Output) It is nonzero if and only if the video system 
can not be removed from the user's terminal. 
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Name: window 

The window_ subroutine provides a terminal independent interface to video terminal 
operations. More specifically, it controls and performs I/O to a window. 

The window_ subroutine is used in conjunction with the iox_ subroutine call entry points in 
the window_io_ I/O module. The window_ and video_utils_ subroutines together perform the 
same functions as the window_call command. 

The virtual terminal implemented by window_ corresponds closely to common video terminals. 
The features of the terminal are defined implicitly by the entries below. Not all entries can 
be supported on all terminals. The result of calling an unsupported feature is the error code 
video_et_$capability_lacking. Programs can determine whether the device in question supports 
a given operation by using a get_capabilities control order, described under the window_io_ 
I/O module. 

Additional terminals may be supported by defining their video attributes in the Terminal Type 
File (TTF). The TTF is described in the Multics Programmer's Reference Manual, Order | 
No. AG91. I 

Some entry points require that the current cursor position be defined when they are called. 
The current position is defined unless a call is made to the write_raw_text entry point, or an 
asynchronous event changes the window contents. If the current position is not defined, these 
entry points will return the status code video_et_$cursor_position_undefined. 

If an asynchronous event changes the state of the window, status will be set for the window. 
Once window status is set, all calls to window_ on that window will return the status code 
video_et_$window_status_pending until a get_window_status control order is used to pick up 
the status. 

The calling sequences for all the entry points are in the include file window_dcls.incl.pll. 



Entry: window ^$bell 

This entry activates the terminal alarm. For most terminals, this will be the audible bell. For 
some it will be a visible signal. 

USAGE 

declare wi.ndow_$be1 1 entry (ptr, fixed bin (35)) » 
caii window_$Den (iocb_ptr, code); 
ARGUMENTS 
iocb_ptr 

is a pointer to an lOCB for a switch attached with window_io_. (Input) 

code 

is a standard system error code. (Output) 
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NOTES 

The current cursor position must be dfined for this call. If the cursor is in some other 
window on the screen when this call is made, it is moved to the current position in this 
window. 

Entry: window ^$change_coliimn 

This entry moves the cursor to a different column on the current line, without changing the 
line. 

USAGE 

declare wi ndow_$change_col umn entry (ptr, fixed bin, fixed bin (35)); 
call wi ndow_$change__column (iocb__ptr, new_column, code); 
ARGUMENTS 
iocb_ptr 

is a pointer to an lOCB for a switch attached with window_io_. (Input) 

new_column 

is the new column. (Input) 

code 

is a standard system error code. (Output) 
NOTES 

The current cursor position must be defined. 
Entry: window__$change__line 

This entry moves the cursor to a new line without changing the column. 
USAGE 

declare window_$change_l ine entry (ptr, fixed bin, fixed bin (35)); 

call wi ndow_$change__l i ne (iocb__ptr, new_line, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to an lOCB for a switch attached with window_io_. (Input) 

new_line 

is the new line. (Input) 
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code 

is a standard system error code. (Output) 



Entry: window_$clear__region 

This entry replaces the contents of the r^on specified with spaces, and leaves the cursor at 

the upper left-hand corner of the region. The region is defined by giving the upper 
left-hand corner (line and column), and the width and height of the region. 

USAGE 

declare window__$clear_region entry (ptr, fixed bin, fixed bin, fixed bin, 
fixed bin, fixed bin (35)); 

call wi ndow_$clear_region (iocb_ptr, start_line, startled, n_lines, n_cols, 
code) ; 

ARGUMENTS 

iocb_ptr 

is a pointer to an lOCB for a switch attached with window_io_. (Input) 
start_line 

is the number of the line where clearing will begin. (Input) 
start_col 

is the number of the column where clearing will begin. (Input) 
n_lines 

is the number of lines which will be cleared. (Input) 
n_cols 

is the number of columns which will be cleared. (Input) 

code 

is a standard system error code. (Output) 
NOTES 

The rectangular r^on described in cleared. The cursor position defined at (start_line, 
start_col). 
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Entry: window ^$clear__to__end_of__line 

This entry clears everything to the right of the cursor on the current line to spaces. Positions 
to the left of the cursor are not affected. The cursor is not moved. 

USAGE 

declare wi ndow_$clear_to_end_of_l i ne entry (ptr, fixed bin (35)) » 
call window_$clear_to__end_of_l ine (iocb_ptr, code); 
ARGUMENTS 
iocb_ptr 

is a pointer to an lOCB for a switch attached with window_io_. (Input) 

code 

is a standard system error code. (Output) 
NOTES 

The cursor position must be defined. 

Entry: window_$clear_to__end__of__window 

This entry clears all of the window between the cursor and the end of the window. This 
includes everything to the right of the cursor on the current line, and all lines below the 
cursor. The cursor is not moved. 

USAGE 

declare window__$clear_to_end__of__window entry (ptr, fixed bin (35)); 
call window_$clear_to_end__of__window (iocb__ptr, code); 

ARGUMENTS 
iocb_ptr 

is a pointer to an lOCB for a switch attached with window_io_. (Input) 

code 

is a standard system error code. (Output) 
NOTES 

The current cursor position must be defined. 
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Entry: window $clear window 

This entry clears the entire window to spaces, and leaves the cursor at home. 
USAGE 

declare wi ndow_$clear_wi ndow entry (ptr, fixed bin (35)); 
call wi ndow__$c lea r_wi ndow (iocb_ptr, code); 
ARGUMENTS 
iocb_ptr 

is a pointer to an lOCB for a switch attached with window_io_. (Input) 

code 

is a standard system error code. (Output) 
NOTES 

The cursor position is defined to be at line 1, column 1 after the screen is cleared. 
Entry: window_$create 

This entry creates a new window on the terminal screen. 
USAGE 

declare window_$ create entry (ptr, ptr, ptr, fixed bin (35) ) » 

call wi ndow_$create (terminal__iocb__ptr , window_info__ptr , wi ndow_iocb_ptr , 
code) ; 

ARGUMENTS 

terminal_iocb_ptr 

is a pointer to an lOCB for the terminal control switch. (Input) Normally this should be 
video_data_$terminaLiocb. 

window_info_ptr 

is a pointer to a standard window_jx>sition_info structure, as declared in 
window_controLinfo.incl.pll. (Input) 

window_iocb_ptr 

is a pointer to a detached lOCB pointer. (Input) It may be obtained with iox_$find_iocb 
which must be done before the call to window_$create. For example: 

call iox__$f ind_iocb ("top_window", window_iocb_ptr , code); 
where the value returned for window_iocb_ptr is used in the call to window_$create. 
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code 

is a standard system error code. (Output) 

NOTES 

The window_info_ptr must point to a window_position_info structure, as declared in 
window_control_info.incl.pll. If window_position_info. width is set to zero, the window will 
occupy the full width of the screen. Currently windows must occupy the full width of the 
screen. If tc_io_.*.*in window_position_info.height is set to zero, the remainder of the screen 
is used. The iocb_ptr is an input argument, iox_$find_iocb may be used to obtain an 
iocb_ptr for a new switch. 



Entry: wmdow__$delete ^chars 

This entry deletes characters on the current line. Characters to the right of the cursor are 
moved to the left Character positions opened up on the right margin are filled with spaces. 
It is an error to call this entry point if the terminal does not support the delete chars 
operation. 

USAGE 

declare wi ndow__$del ete_chars entry (ptr, fixed bin, fixed bin (35)); 

call wi ndow_$delete_chars (iocb_ptr, n_chars, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to an lOCB for a switch attached with window__io_. (Input) 
n_chars 

is the number of characters (starting at the current cursor position) that will be removed 
from the screen. (Input) If n_chars is zero, no action is taken. 

code 

is a standard system error code. (Output) 
NOTES 

The current cursor position must be defined. The number of characters specified by n_chars 
are deleted, and the remaining characters on the line, if any, move leftward to occupy the 
space. 
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Entry: window_$destroy 

This entry destroys an existing window, leaving its lOCB in a detached state. 
USAGE 

declare window_$destroy entry (ptr, fixed bin (35)) » 

call wi ndow_$destroy (wi ndow_iocb_ptr, code); 

ARGUMENTS 

window_iocb_ptr 

is a pointer to an lOCB attached with window_$create. (Input) 

code 

is a standard system error code. (Output) 



Entry: window__$edit line 

This entry allows applications to preload the video editor input buffer with a string. 
USAGE 

declare wi ndow_$ed i t_l i ne entry (pointer, pointer, pointer, fixed bin (21), 
fixed bin (21), fixed bin (35)); 

call window_$edi t_l ine (iocb_ptr, wi ndow_edi t_l i ne_i nf o_ptr , buffer__ptr, 
buffer__len, n_returned, code) ; 

ARGUMENTS 

window_iocb_ptT 

is a pointer to an lOCB for a switch attached with window.io. (Input) 

window_edit_line_inf o_ptr 

is a pointer to a window_edit_line_info structure, as declared in window_control_info.incl.pll 
(described below). (Input) 

version 

is the version number of the structure. (Input) This is currently window_edit_line_version_l. 
line_ptr 

is a pointer to the initial text string to be loaded into the input buffer before editing 
begins. (Input) 

line_length 

is the length of the string pointed to by line_ptr. (Input) 
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buffer_ptr 

is a pointer to a buffer where the users input will be put (Input) 

buffer_len 

is the size of the input buffer. (Input) 

n_returned 

is the number of characters in the final output line. (Output) 

code 

is a standard system error code. (Output) 



Entry: window___$get_cursor_position 

This entry is used to return the current position of the cursor. If the last operation done to 
the terminal was in some other window, this will not be the actual position of the cursor on 
the screen. 

USAGE 

declare window__ $get__cursor_posi t ion entry (ptr, fixed bin, fixed bin, fixed 
bin (35)); 

call wi ndow_$get_cursor_posi tion (iocb_ptr, line, col, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to an lOCB for a switch attached with window_io_. (Input) 

line 

is the line number. (Output) 

col 

is the column position. (Output) 

code 

is a standard system error code. (Output) 
NOTES 

The current cursor position must be defined. 
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Entry: window ^$get ^echoed ^chars 

This entry accepts input from the typist, echoing the characters as typed, until either a 

specified number of characters are read, or a break character is encountered. By default, the 

break characters are the control characters plus DEL (177 octal). 

USAGE 

declare wi ndow_$get_echoed_chars entry (ptr, fixed bin (21), char (*) , fixed 
bin (21), char (1) varying, fixed bin (35)); 

call wi ndow__$get_echoed_chars (iocb__ptr, n_to_get, buffer, n__got, break, 
code) ; 

ARGUMENTS 

iocb_ptT 

is a pointer to an lOCB for a switch attached with window_io_. (Input) 
n_to^et 

is the number of columns (N) between the cursor and the end of the line. (Input) At 
most N characters will be returned. 

buffer 

is the caller-supplied buffer that holds characters returned. (Input) 
n_got 

is the number of characters returned. (Output) Each character is echoed, 
break 

is the character that causes the echoing to stop. (Output) This character is not echoed. 

code 

is a standard system error code. (Output) 
NOTES 

This entry point returns no more than n_to_get characters in buffer. It reads and echoes 
characters until either (1) it has read n_to_jet characters, or (2) it has read a break 
character. If it stops due to a break character, the break character is returned in break, 
otherwise break is equal to 
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Entry: wmdow_$get__one__iinechoed__char 

This entry reads a single character, unechoed, from the terminal. Optionally, it can return 
instead of waiting if there are no characters available. 

USAGE 

declare window_$get_one_unechoed__char entry (ptr, char (1) varying, bit (1) 
aligned, fixed bin (35)); 

call wi ndow_$get_one__unechoed_char (iocb__ptr, char_read, block_flag, code); 

ARGUMENTS 
iocb_ptr 

is a pointer to an ICK!B for a switch attached with window_io_. (Input) 
char_read 

is the read character. (Output) If block_flag is "0"b, and no input is typed ahead, then 
this will be a zero length character string. 

block_flag 

if this flag is "l"b, input from the terminal is awaited if none is available. (Input) If it 
is "0"b, and no input is available, then this entry returns immediately, and sets char_read 
to 

code 

is a standard system error code. (Output) 
NOTES 

Beware of the PL/ 1 language definition of character string comparisons when using this entry 
with a block flag of "0"b. In PL/ 1, both of the following comparisons are true: 

^11 II _ II 11^ 
(III. « .1 II) 

That is, a zero length varying string compares equally to a single space. To test if char_read 
is nonempty, use an expression like: 

(length (char_read) > 0) 
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Entry: wmdow__$gct__imechoed__chars 

This entry accepts input from the typist, leaving it unechoed, until either a specified number 
of characters are read, or a break character is encountered. 

USAGE 

declare wi ndow_$get_unechoed_chars entry (ptr, fixed bin (21), char (*) , fixed 
bin (21), char (1) varying, fixed bin (35)); 

call wi ndow__$get_unechoed_chars (iocb_ptr, n_to_get, buffer, n__got, break, 
code) ; 

ARGUMENTS 

iocb_ptr 

is a pointer to an lOCB for a switch attached with window_io_. (Input) 
n_to_get 

is the number of columns (N) between the cursor and the end of the line. (Input) At 
most N characters will be returned. 

buffer 

is the caller-supplied buffer that holds characters returned. (Input) 
n_got 

is the number of characters returned. (Output) Each character is echoed, 
break 

is the character that causes the echoing to stop. (Output) This character is not echoed. 

code 

is a standard system error code, (Output) 
NOTES 

This entry point will read no more than n_to_get characters from the terminal, without 
echoing them to the typist. The characters are returned in the buffer. Characters are read 
until either (1) n_to_get characters are read, or (2) a break character is read. If reading 
stops due to a break character, then the break character is returned in break. Otherwise 
break is "". 
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Entry: wmdow_$msert__text 

This entry inserts text at the current cursor position; Text at the cursor or to the right of 
the cursor is shifted to the right, to accommodate the new text It is an error to call this 
entry if the terminal does not support the insertion of text 

USAGE 

declare wi ndow__$ i nsert_text entry (ptr, char (*) , fixed bin (35)); 

call window_$insert__text (iocb__ptr, text, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to an lOCB for a switch attached with window_io_. (Input) 

text 

is the character string to be written. (Input) When converted to output, each character in 
this string must occupy exactly one print position. The length of this string must be such 
that characters moved to the right will remain on the current line in the window. If 
these conditions are not met, the result is undefined. The cursor is left after the last 
character inserted. 

code 

is a standard system error code. (Output) 
NOTES 

The current cursor position must be defined. The string "text" must contain only printable 
ASCII graphics. If it contains any other characters, the status code video_et_$string_not_printable 
is returned. 



Entry: window $overwrite ^text 

This entry writes text on the window in the current cursor location. If there is any text at 
or to the right of the current cursor position in the window, it is overwritten with the 
supplied string. 

USAGE 

declare wlndow__$overwr i te_text entry (ptr, char (*) , fixed bin (35)); 

call wi ndow__$overwr i te_text (iocb_ptr, text, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to an lOCB for a switch attached with window_io_. (Input) 
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text 

is the character string to be written. (Input) This string should consist of only printable 
ASCII graphics (octal codes 040 throu^ 176 inclusive), and may not be longer than the 
space remaining on the current line. 

code 

is a standard system error code. (Output) 
NOTES 

The cursor position must be defined. The string "text" may contain only printable ASCII 
graphics. If it contains anything else the status code video_et_$string_not_printable is 
returned. 



Entrjr: window__$position_cursor 

This entry moves the cursor to any requested position in the window. It defines the current 
cursor position if it is undefined. 

USAGE 

declare wi ndow_$posi t ion__cursor entry (ptr, fixed bin, fixed bin, 
fixed bin (35)) ; 

call wi ndow_$pos i t ion_cursor (iocb__ptr, line, col, code); 

ARGUMENTS 

iocb_ptr 

is a pointer to an lOCB for a switch attached with window_io_. (Input) line is the line 
number. (Input) 

col 

is the column position. (Input) 

code 

is a standard system error code. (Output) 



Entry: wmdow_$positioii^cursor_rel 

The entry moves the cursor relative to the current location. 
USAGE 

declare window__$posi tion__cursor_rel entry (ptr, fixed bin, fixed bin, 
fixed bin (35)) ; 

call window__$posl tion_cursor_rel (iocb_ptr, nne_inc, col_inc, code); 
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ARGUMENTS 
iocb_ptr 

is a pointer to an I(XB for a switch attached with window_io_. (Input) 
line_inc 

is the change in line number, (input) If line_inc is a positive number, the cursor is 
moved down. If it is a negative number, the cursor is moved up. If it is zero, the 
cursor's line number is not changed. 

col_inc 

is the change in colunm position. (Input) If col_inc is a positive number, the cursor is 
moved to the right If it is a negative number, the cursor is moved to the left If it is 
zero, the cursor's column position is not changed. 

code 

is a standard system error code. (Output) 



Entrjr: window_$scroll region 

This entry scrolls a region up or down a given number of lines. A positive scroll count 
scrolls the window up, deleting lines from the top of the window and adding new blank lines 
to the bottom. The cursor's new position is at the beginning of the first new blank line. A 
negative count scrolls the window down, deleting lines from the bottom and adding lines to 
the top. The cursor is left at home. If this entry is called and the terminal does not 
support either scrolling or insert and delete lines, the result is an error status, 
video_et_$capabilities.lacking. 

USAGE 

declare wi ndow_$ scroll _r eg i on entry (ptr, fixed bin, fixed bin, fixed bin, 
fixed bin (35)) ; 

call wlndow_$scrol l_region (iocb__ptr, start^line, n_lines, scrol l__di stance, 
code) ; 

ARGUMENTS 

iocb_ptr 

is a pointer to an lOCB for a switch attached with window_io_. (Input) 
start_line 

is the number of the first line of the region. (Input) 
n_lines 

is the number of lines that compose the region. (Input) 
scrolLdistance 

is the distance in lines by which the region will be scrolled. (Input) 
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code 

is a standard system error code. (Output) 
NOTES 

The cursor position is defined to be column one on first_line. The region from first_line for 
n.lines is scrolled scrolLdistance lines, which may be negative. 



Entry: wmdow_$syTic 

This entry synchronizes the process with the typist by writing any pending output to the 
terminal. 

USAGE 

declare window_$sync entry (ptr, fixed bin (35) ) » 
call window_$sync (iocb__ptr, code); 
ARGUMENTS 
iocb_ptr 

is a pointer to an lOCB for a switch attached with window_io_. (Input) 

code 

is a standard system error code. (Output) 
NOTES 

The calling process is made to wait until the typist types something after the last text output 
has been transmitted to the terminal. 



Entry: window ^$write__raw_text 

This entry is used to output a terminal dependent sequence. The current cursor position 
becomes undefined after this call is made. This entry should not be used to output sequences 
that put graphics onto the terminal screen, as the video system's internal screen image will 
become inconsistent This entry is used for terminal-specific features that cannot be accessed 
via the video system. 

declare wi ndow__$wr i te_raw__text entry (ptr, char (*) , fixed bin (35)); 
call wi ndow_$wr i te_raw_text (iocb_ptr, text, code); 
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ARGUMENTS 
iocb_ptr 

is a pointer to an lOCB for a switch attached with window_io_. (Input) 

text 

is any string of printable ASCII characters to be transmitted to the terminal. (Input) 

code 

is a standard system error code. (Output) 
NOTES 

Any call to window_$write_raw_text causes the cursor position to become undefined and sets 
the screen_invalid window status flag. Subsequent calls to write_raw_text will ignore this flag, 
but all other window_ entrypoints will return the status code video_et_$window_status_pending 
until the status flag is cleared. It is the responsibility of the application performing the raw 
output call to perform a get_window_status control order to clear the status flag. 



Entry: window ^$write ^sync read 

This entry writes a prompt, synchronizes input to the output of the prompt, and reads a 
response. This entry is useful for queries where it is important to avoid interpreting 
type-ahead as a response to a question. 

USAGE 

declare wi nclow_$wr i te_sync_read entry (ptr, char (*) , fixed bin (21), 
char (*) , fixed bin (21), char (1) varying, fixed bin (35)); 

call wi ndow_$wr i te__sync_read (iocb__ptr, prompt, n_to_get, buffer, n_got, 
brealc, code) ; 

ARGUMENTS 

iocb_ptr 

is a pointer to an ICKB for a switch attached with window_io_. (Input) 
prompt 

is a string of printable ASCII characters which must fit on the current line. (Input) 
n_to_get 

is the number of columns (N) between the cursor and the end of the line. (Input) At 
most N characters will be returned. 
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buffer 

is the caller-supplied buffer that holds characters returned. (Input) 
n_got 

is the number of characters returned. (Output) Each character is echoed, 
break 

is the character that causes the echoing to stop. (Output) This character is not echoed. 



code 

is a standard system error code. (Output) 



NOTES 



The current cursor position must be defined. Tnis entry overwrites the text string "prompt" 
at the current cursor position. It then reads characters typed after the prompt has been 
transmitted to the terminal. The characters are read in the same fashion as the 
get_unechoed_chars entry point Any characters read before the prompt is transmitted, are 
buffered and returned to get_echoed_chars or subsequent get_unechoed__chars calls. 



6-31 



CP51-02 



SECTION 7 
I/O MODULES 



This section contains descriptions of the I/O modules used by the menu and video 
software, presented in alphabetical order. For details on I/O processing, see the Multics \ 
Programmer's Reference Manual^ Order No. AG91. j 
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Name: tc_Jo__ 

The tc_io_ I/O module supports terminal independent I/O to the screen of a video terminal. 

Entry points in this module are not called directly by users; rather, the module is accessed 
through the I/O system interfaces iox_. 

ATTACH DESCRIPTION 



tc_io_ {device} {-control__args} 



ARGUMENTS 
device 

is the channel name of the device to be attached If a device is not given, the 
-login_channel control argument must be given. 

CONTROL ARGUMENTS 

-login_channel 

specifies attachment to the user's primary login channel. If a device is not specified, 
then the user's login channel is used. This control argument flags this switch for 
reconnection by the process disconnection facility. If the user's login device should hang 
up, this switch will be automatically closed, detached, attached, and opened on the user's 
new login channel when the user reconnects, if permission to use this facility is specified 
in the SAT and PDT for the user. 

-destination DESTINATION 

specifies that the attached device is to be called using the address DESTINATION. In 
the case of telephone auto_call lines, DESTINATION is the telephone number to be 
dialed. See the dial_manager_ subroutine in the Multics Subroutines and 110 Modules 
manual. Order No. AG93, for more details. 

-no_block 

specifies that the device is to be managed asynchronously. The tty_ subroutine will not 
block to wait for input to be available or output space to be available. This control 
argument should not be used on the login channel, because it will cause the command 
listener to loop calling get_chars. 

-no_hangup_on_detach 

prevents the detach entry point from hanging up the device. This is not meaningful for 
the login channel. 

-hangup_on_detach 

causes the detach entry point to hang up the device automatically. This is not meaningful 
for the login channel. 
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OPEN OPERATION 

Opens the module for stream.input.output 

GET LINE OPERATION 

The get_line operation is not supported. 

CONTROL OPERATION 

The following control orders are supported: 

clear_screen 

clears the entire terminal screen. The info_ptr is null. It is intended for use when the 
screen image may have been damaged due to communications problems, for example. 

get_capabilities 

returns information about the capabilities of the terminal. The info structure is described 
in the description of the "get_capabilities*' control order in the window_io_ module. 

get_break_table 

returns the current break table. The info pointer should point to a break table, declared 
as follows (window_control_info.incl.pll): 

del 1 break_table_i nf o aligned based (break_tabl e_ptr) , 
2 version fixed bin, 

2 breaks (0:127) bit (1) unaligned; 



STRUCTURE ELEMENTS 



version 

must be set by the caller to break_table_infc_version_l. (Input) 
breaks 

has a "l"b for each character that is a break character. (Output) 
set_break_table 

sets the break table. The info pointer should point to a break table as defined by the 
get_break_table order, above. By default, the break table has "l"b for all nonprintable 
characters, and "0"b elsewhere. Applications that set the break table must be careful to 
reset it afterwards, and establish an appropriate cleanup handler. 

set_line_speed 

sets the speed of the terminal's connection to Multics. The info_ptr should point to a 
fixed binary number representing the Hne speed in characters per second. Negative line 
speeds are not allowed. 
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set_term_type 

changes the terminal type. The info pointer should point to a set_term_type_info 
structure, described below. This sets window_status_pending for all windows and sets the 
ttp_change field in the window_status structure along with the screen_in valid. This 
operation re-initializes all the terminal specific video system information such as the 
video sequences, length and width of the screen, and capabilities. It is equivalent to 
doing "window_call revoke; stty -ttp new_terminal_type; window_call invoke", except no 
windows are destroyed. The set_term_type_info structure is declared in 
set_term_type_inf o.incl.pll: 

del 1 set__term__type_i nfo aligned based (sttip) 

2 version fixed bin 

2 name char (32) unaligned 

2 f 1 ags unal i gned 

3 send__i ni ti al__str i ng bit (1) 

3 set_modes bit (1) 

3 ignore line__type bit (1) 

3 mbz " bit (33) ; 



STRUCTURE ELEMENTS 



version 

is the version of this structure. (Input) It must be stti_version_l. 
name 

is the name of the new terminal type. (Input) 

NOTES 

The send_initial_slring, set_modes and ignore_line_type flags are all ignored by the video 
system. The initial string will always be sent 

reconnection 

determines the new terminal type (which may or may not be the same as before the 
disconnection). Performs a set_term_type control order to inform the rest of the system 
of the change in terminal type. If the set_term_type fails then the 
video_utils_$turn_off_login_channel is invoked in an attempt to re-attach tty_. Reconnection 
(a field in window_status) is set to indicate to an application doing get_window_status 
that a reconnection has occurred. 

The window_status_info structure is declared in window_status.incl.pll. 
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Name: window io 

The window_io_ I/O module supports I/O tx) a window. In addition to the usual iox_ 
entries, the module provides terminal independent access to special video terminal feature, 
such as a moveable cursor, selective erasure, and scrolling of regions. The module provides a 
real-time input line editor and performs output conversion and "MORE" processing. 

Entry points in this module are not called directly by users; rather, this module is accessed 
through the I/O system interfaces iox_ and window_. 

ATTACH DESCRIPTION 



window_io__ swi tch {-control_args} 



ARGUMENTS 
switch 

is the name of an I/O switch attached to a terminal via the tc_io_ I/O module. The 
window created by this attach operation will be mapped onto the screen of tJiat terminal. 
Use window_$create to attach and open, and use window_$destroy to detach and close 
windows on the login terminal. 



CONTROL ARGUMENTS 
-firstjine LINE_NO 

LINE_NO is the line number on the screen where the window is to begin. If omitted, 
the window starts on the topmost line of the screen (line 1). 

-height N_LINES. -njines N_LINES 

N_LINES is the number of lines in the window. The default is to use all lines to the 
end of the screen. 

-first_column COL_NO 

COL_NO is the column number on the screen where the window is to begin. If omitted, 
the window starts on the leftmost column of the screen (column 1). 

-width N_COLS. -n_columns N_COLS 

N_COLS is the number of the columns in the window. The default is all columns to the 
end of the screen. 

NOTES 

The attach description control argimients must specify a region which lies within the terminal 
screen. If not, the attachment is not made, and the error code video_et_$out_of_terminal_bounds 
is returned. 

When the window is attached, it is cleared and the cursor is left at home. 
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OPEN OPERAT!ON 

The following opening mode is supported: stream_input_output 
PUR CHARS OPERATION 

This operation is used to output a character string to the window. If rawo mode (see below) 
is disabled, the characters are processed according to the output conversions defined for the 
terminal. If necessary, the string is continued on subsequent lines of the window. If output 
passes the last line of the window, the placement of additional lines is controlled by the 
setting of the more_mode mode (see below). If an output line must be erased from the 
window to make room for this new output, and there has been no intervening input in this 
window, and more.mode (see below) is enabled, the user is queried for the disposition of this 
new output (See MORE processing in Section 4.) 

In rawo mode, the characters are written directly to the terminal, without any of the above 
processing. 

GET CHARS OPERATION 

This operation returns exactly one character, unechoed, regardless of the size of the caller's 
buffer. The line editor is not invoked by this call. 

GET LINE OPERATION 

The get_line operation invokes the real-time input line editor, and returns a complete line 

typed by the user. A description of the typing conventions is given in Section 4. The 

put_chars and get_line operations retrieve and reset any statuses that they encounter, so that 

applications that make these calls need not be changed to check for 
video_et_$window_status_pending. 

CONTROL OPERATION 

The control operations below are supported. Note that many of the control operations can be 
issued at command level via io_call commands; these include any control orders that do not 
require an info structure, and those described below. The following relations must hold when 
changing windows (set_window_info). These relations are always true when obtaining 
information about a window (get_window_info): 

0 < column + width <= screen width 
0 < line + height <= scrren height 
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get_window_inf o 

returns information about the position and extent of the window. The info ptr points to 
the following structure (declared in window_controUinfo.incl.pll): 

del 1 window_posi tion__info based (window_posi tion_info_ptr) , 

2 version fixed bin, 
2 origin, 

3 column fixed bin, 

3 1 i ne f i xed bin, 
2 extent, 

3 width fixed bin, 

3 height fixed bin; 



STRUCTURE ELEMENTS 



version 

is the version number of this structure. (Input) It must be 
window_position_inf o_version_2. 

column 

is the column of the upper left-hand corner of the window. (Output) If the column 
of the upper left-hand comer is zero, then the first column will be used, to allow 
old programs written when this was a mbz field to run without modification. 

line 

is the line of the upper left-hand comer of the window. (Output) * 
width 

is the width of the window (columns). (Output) 
height 

is the height of the window (hues). (Output) 
set__window_info 

causes the window to be relocated or to change size (or both). The info ptr points to 
the same structure used in the "get_window_info" control order. The values have the 
same meaning, but are the new values for the window when setting (Input), and are 
retumed by get_window_info (Output). 
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get_window_status, set_window_statiis 

window status is used to inform the application that some asynchronous event has 
disturbed the contents of the window. When window status is set for a window, all calls 
to window_ will return video_et_$window_status_pending until the status is reset To 
reset the status, make a get_window_status control order on the switch. The info pointer 
should point to the following structure (declared in window_control_info.incl.pll): 



del 1 wi ndow_status_i nfo aligned based (wi ndow_status__i nf o__ptr) , 
2 version fixed bin, 

2 status_str i ng bit (36) aligned; 



STRUCTURE ELEMENTS 



version 

is the version of this structure. (Input) It must be window_status_version_l. 



status_string 

is the window status information. (Input) 
the include file window_status.incl.pll: 



To interpret the actual status_string, use 



del 1 wi ndow_status_i nf o 
2 screen_i nval id 
2 async_change 
2 ttp_ehange 
2 reconnect ion 
2 pad 



aligned based (wi nclow_status_i nfo_ptr) 

bit (1) unaligned, 

bit (1) unal t gned, 

bit (1) unaligned, 

bit (1) unal i gned, 

bit (32) unaligned; 



STRUCTURE ELEMENTS 



screen_invalid 

indicates that the contents of the window have become undefined. (Input for set. 
Output for get) Tnis will happen, for example, in the event of a 
disconnection/reconnection of the terminal. 

async_change 

indicates that a timer or event call procedure has made a modification to the 
window. (Input for set. Output for get) 

ttp_change 

indicates that the terminal type has changed. (Input for set. Output for get) This 
re-initializes all the terminal specific video system information such as the video 
sequences, length and width of the screen, and capabilities. 
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reconnection 

determines the new terminal type (which may or may not be the same as before the 
disconnection). (Input for set. Output for get) Performs a set_term_type control 
order to inform the rest of the system of the change in terminal type. 



pad 



NOTES 



reserved for future expansion and must be "0"b. 



The get_window_status and get_window_status control orders are available from command level 
and as active functions with the following io_call conmiands: 

io_cal1 control wi ndow__swi tch get_wi ndow_status status__key_l 

{status_key_2} N 
io_call control wi ndow__swi tch set__wl ndow_status status_key_l 

{status__key_N} 

where status_key_N is either screen_invalid, asynchronous_change, ttp_change, or reconnection. 



get_capabilities 

returns information about the generic capabilities of the terminal. These are the "raw" 
physical characteristics of the terminal. The video system may simulate those that are 
lacking. For example, the system simulates insert and delete characters, but does not 
simulate insert and delete lines. The info ptr should point to the following structure 
(declared in terminal_capabilities.incl.pll): 



del 1 capabi 1 i ties_info 

2 version 

2 screensize, 
3 columns 
3 rows 

2 flags, 

3 scrol l_region 
3 insert__chars 
3 insert_mode 
3 delete__chars 
3 overprint 
3 pad 

2 1 i ne_speed 



a 1 i gned based (capab i 1 i t i es__i nf o_ptr) , 
fixed bin, 

fixed bin, 
fixed bin. 



bit 
bit 
bit 
bit 
bit 
bit 



unal , 
unal , 

unal , 
unal , 
unal , 



28) unal. 



fixed bin, 



STRUCTURE ELEMENTS 



version 

is the version number of this structure. (Input) It must be capabilities_info_version_l, 
also declared in the include file. 
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columns 

is the number of columns on the tenninal. (Output) 

rows 

is the number of rows (lines) on the terminal. (Output) 
scroll_region 

is true if the terminal is capable of scrolling, with insert and delete lines. (Output) 
insert_chars 

is true if the insert.chars function is supported. (Output) 
insert_mode 

is true if the terminal is capable of going into and out of insert mode. (Output) 
delete_chars 

is true if the delete chars function is supported. (Output) 

overprint 

is true if the terminal is capable of printing overstrike characters. (Output) It is 
currently always set to "0"b (false). 

pad 

reserved for future expansion and must be "0"b. 
line_speed 

is the speed of the communications channel to the terminal, in characters per second. 
(Output) 

reset_more 

causes MORE Processing to be reset All lines on the window may be freely discarded 
without querying the user. 

get_editing_chars 

is identical to the operation supported by the tty_ I/O module. 

set_editing_chars 

is identical to the operation supported by the tty_ I/O module. 
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NOTES 

The get_editing^chars and set_editing_chars control orders are available from command level 
and as active functions with the following io_call commands: 

1o__call wi ndow__swi tch get_edi ting_chars 

io^call control wIndow_swi tch set_edi ting_chars erase_ki 1 l_characters 



get_more_responses 

returns information about the acceptable responses to MORE processing. The info pointer 
should point to the following structure (declared in window_control_info.incl.pll): 

del 1 more_responses__info aligned based (more_responses_l nfo_ptr) , 

2 version fixed bin, 

2 n_yeses fixed bin, 

2 n_noes fixed bin, 

2 yeses char (32) unaligned, 

2 noes char (32) unaligned; 



STRUCTURE ELEMENTS 



version 

is the version number of this structure and must be set to more_responses_info_version_l, 
also declared in the include file. (Input) 

n_yeses 

is the number of different affirmative responses, from zero to 32. (Output) 
n_noes 

is the number of different negative responses. (Output) 
yeses 

is the concatenation of all the affirmative responses. (Output) Each response is one 
character. Only the first "n_yeses" are valid. 

noes 

is the concatenation of all negative responses. (Output) Each response is one 
character. Only the first "n_noes" are valid. 

set_more_responses 

sets the responses. The data structure is the same as the one used for the 
•'get_more_responses" order except that all fields are Input. At most, 32 yeses and 32 | 
noes may be supplied. It is hi^ly recommended that there be at least one yes, so that 
output may continue. The "yes" and "no" characters must be distinct If they are not, 
the error code video_et_$overlapping^more_responses is returned, and the responses are 
not changed. 
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NOTES 

The get_more_response and set_more_respoiise control orders are available from command 
level and as active functions with the following io_call command: 

io__can control window_swi tch get_more_responses 
io__can control window_swi tch set_more_responses yes__responses 
no__responses 

where the yes_responses and no_responses will be used as arguments to the get_more_responses 
control order. If either of the response strings contains blanks or special characters, it must 
be quoted. 

get_more_prompt set_more_prompt 

sets the prompt displayed when a more break occurs. The current more responses can be 
displayed as part of the more prompt, by including the proper ioa_ control codes as part 
of the prompt string. For example the default video system more prompt string is 
"More? C^a for more; '^a to discard output)". With the default more responses of 
carriage return for more and the delete for discard, the final string displayed is "More 
(RETURN for more; DEL to discard output)." The info pointer should point to the 
following structure (declared in window_controLinfo.incl.pll): 

del 1 more_prompt_i nf o aligned based (more_prompt_i nf o_ptr) , 
2 version char (8) , 

2 more_prompt char (80) ; 

STRUCTURE ELEMENTS 



version 

is the version niraiber of this structure (currently more_prompt_info_version_l). 
(Input) 

more_prompt 

is the ioa_ control string to serve as the more prompt (Input for set Output for 
get) 
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The get_more_prompt and set_more_prompt corxtrol orders are available from command level 
and as active functions with the following io_call command: 

io_call control wi ndow_swl tch get_more_prompt 

io__call control wl ndow_swi tch set__more_'-,-ompt prompt__str i ng 

where window_switch is a valid window_io_ switch and prompt_string is the ioa_ control 
string described above. 

get_more_handler set_more_handler 

Sets the handler for video system more breaks to the specified routine. The info pointer 
should point to the following structure (declared in window_control_io.incl.pll): 

del 1 more_handler_i nfo aligned based (more_handler_info__ptr) , 

2 version fixed bin, 

2 flags unal igned, 

3 old_handler_val id bit{l), 

3 pad bit (35) . 

2 more_handler entry (pointer, bit(l) aligned), 

2 old_more_handler entry (pointer, bit(l) aligned); 

del (more_handler_info_version_3) » 

fixed bin internal static options (eonstant) init (3); 



STRUCTURE ELEMENTS 



version 

is the version number of this structure, and must be set to more_handler_info_version_3 
(also declared in the include file). (Input) 

more_handler 

is the entry to be called at a more break. (Input for set) (Output for get) It will 
be passed two arguments, described below. 

old_handler_valid 

is a flag specifying whether some other user-supplied more handler was in effect 
when the order call was made. (Output) (This can only be used with get) 

old_more_handler 

is the user supplied entry that was acting as more handler before the order call was 

made. (Output) Its value is only defined if the oldJiandler_valid flag is on. (This 
can only be used with get) 

The more handler routine is called with two arguments. The first is a pointer to a 
structure containing information of interest to a more handler (see below), and the 
second is a flag which the more handler sets to indicate whether or not output should 
be flushed ("l'*b to continue output. "0"b to flush output). 
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The structure can be found in tiie include file window_more_handler.incl.pll, and is 
declared as follows: 



del 1 more__info 
2 version 
2 more_mode 
2 wi ndow_iocb_prt 
2 more_prompt 
2 more__responses, 
3 n_yeses 
3 n__noes 
3 more_yeses 

3 more_noes 



aligned base (more_i nf o_ptr) , 
fixed bin, 

fixed bin, /* which flavor */ 

pointer, /* for window that MORE'd */ 

character (80) , /* MORE? */ 

fixed bin, 
fixed bin, 

character (32) unaligned, 

/* at most 32 yeses */ 
character (32) unaligned; 



STRUCTURE ELEMENTS 



version 

is the version number of the structure (declared as more_handler_info_version_2 in 
the include file). (Input) 

window_iocb_ptr 

is a pointer to the iocb for the window in which the more break occurred. (Input) 
Prompt output should be written to this switch, and responses should be read from 
it 

more_mode 

is the current more m.ode. (Input) Constants for the different more modes are 
declared in the include file window_io_attach_data.incl.pll. 

more_prompt 

is the current more prompt. (Input) This is the string "More? C^a for more; '^a to 
discard output)" and is user-settable. 

more_responses 

is the current set of more responses, and is declared similarly to the more_responses_info 
structure in the get_more_responses order description above. (Input) 
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NOTES 

The get_more_handler and set„moreJiandler control orders are available from command level 
and as active functions with the following io_call command: 

io^call window__swl tch get_more__handler 

io_ca11 window_swi tch set_more_handler more__hand]er 

where more_handler is the entryname of the routine to be used as the more handler routine. 
The name is converted to an entry using the user's search rules and is then used as described 
in the set_more_handler control order. 

get_break_table set_break_table 

break table determines action of the get_echoed_chars, get_unechoed_chars, and 
write_sync_read entry points of the window_ subroutine. The array "breaks" has a 1 for 
each character that is to be considered a break. By default, the break table has "l"b for 
all the nonprintable characters, and "0"b elsewhere. Applications that set the break table 
must be careful to reset it afterwards, and establish an appropriate cleanup handler. 

del 1 break_table_i nfo aligned based (break_table_ptr) , 
2 versions fixed bin, 

2 breaks (0:127) bit (1) unaligned; 



STRUCTURE ELEMENTS 



versions 

must be set by the caller to break__table_info_version_l. (Input) 
breaks 

has a "l"b for each character that is a break character. (Input/Output) 
reset_more_handler 

cancels the last user-defined more_handler. The reset_more_handler control order is 
available from command level with the following io_call command: 

io call control window switch reset more handler 
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get_output_conversion 

this order is used to obtain the current contents of the specified table. The info_ptr 
points to a structure like the one described for the corresponding "set" order below, 
which is filled in as a result of the call (except for the version number, which must be 
supplied by the caller). If the specified table does not exist (no translation or conversion 
is required), the status code error_table__$no_table is returned. 



set_output_conversion 

provides a table to be used in formatting output to identify certain kinds of special 
characters. The info_ptr points to the following structure (declared in tty_convert.incl.pll). 
If the info_ptr is null, no transaction is to be done. 



del 1 cv__trans_struc 
2 version 
2 default 
2 cv_trans 
3 value 



al igned 
fixed bin, 
fixed bin, 
al igned 

(0:255) fixed bin 



(8) unal igned 



STRUCTURE ELEMENTS 



version 

is the version number of the structure. It must be 2 and declared in tty_convertincl.pll. 
default 

indicates, if nonzero, that the table is the one that was in effect before video was 
invoked. 

values 

are the elements of the table. This table is indexed by the value of a typed input 
character, and the corresponding entry contains the ASCII character resulting from 
the translation. 

get_special 

is used to obtain the contents of the special_chars table currently in use. The info_ptr 
points to the following structure (defined in tty„convertincl.pll): 

del 1 get_special_info_struc aligned 
2 area_ptr ptr, 
2 table^ptr ptr; 
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STRUCTURE ELEMENTS 



area_ptr 

points to an area in which a copy of the current special_chars table is returned. 
(Input) 

table_j)tr 

is set to the address of the returned copy of the table. (Output) 
set_special 

provides a table that specifies sequences to be substituted for certain output characters, 
and characters that are to be interpreted as parts of escape sequences on input Output 
sequences are of the following form (defined in tty_convertincl.pll): 

del 1 c_chars based aligned, 

2 count fixed bin (8) unaligned, 

2 chars (3) char (1) unaligned; 



STRUCTURE ELEMENTS 



count 

is the actual length of the sequence in characters (0<= count <=3). If count is zero, 
there is no sequence. 
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chars 



are the characters that make up the sequence. The info_ptr points to a structure of 
the following form (defined in tty_converLincl.pll): 



del 1 special_chars_struc 
2 
2 
2 



a1 i gned based, 



version 


fixed bin 






defaul t 


fixed bin 


» 




special_chars 








3 nl_seq 


aligned 1 


ike 


c_chars. 


3 cr_seq 


aligned 1 


ike 


c_chars. 


3 bs__seq 


aligned 1 


ike 


c_chars. 


3 tab__seq 


a 1 i gned 1 


ike 


eschars. 


3 vt seq 


a 1 i gned 1 


Ike 


eschars, 


3 ff_seq 


a 1 i gned 1 


ike 


eschars. 


3 printer_on 


a 1 i gned 1 


ike 


c_cliars. 


3 printer_off 


al i gned 1 


ike 


c_chars , 


3 red__r ibbon_shi f t 


aligned 1 


ike 


eschars. 


3 black_ribbon_shift 


aligned 1 


ike 


c_chars, 


3 end_of__page 


aligned 1 


ike 


eschars. 


3 escape__l ength 


f 1 xed b i n 


> 





3 not__ed i ted_escapes 



3 ed i ted_escapes 



3 i nput_escapes 
k 1 en 
k str 



3 i nput_resul ts 
k pad 
k str 



(sc__escape_l en refer 
(spec ial__chars.escape_l ength) ) 

1 i ke c_chars, 
(sc_escape_l en refer 
(special_chars.escape_length) ) 

1 i ke c_chars, 
al i gned, 

fixed bin (8) unaligned, 

char (sc_i nput_escape__len refer 

(special_chars. i nput_escapes . len) ) 

unal i gned, 
al igned, 

bi t (9) unal i gned, 
char (sc__i nput_escape_len refer 
(special__chars. i nput_escapes . len)) 
unal igned; 



NOTES 

Video ignores cr_seg, bs_seg, tab_seg, vt_seg, ff.seg, printer_on, printer_off, end_of_page, 
input.escapes, and input results. 
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STRUCTURE ELEMENTS 



version 

is the version number of this structure. It must be 1. 

default 

indicates, if nonzero, that the default values for the current terminal type and baud 
rate are to be used and that the remainder of the structure is to be ignored. 

nLseq 

is the output character sequence to be substituted for a newline character. The 
nUseq.count generally should be nonzero. 

cr_seq 

is the output character sequence to be substituted for a carriage-return character. If 
count is zero, the appropriate number of backspaces is substituted. However, either 
cr_seq.count or bs_seq.count should be nonzero (i.e., both should not be zero). 

bs_seq 

is the output character sequence to be substituted for a backspace character. If count j 
is zero, a carriage reUm ^d Uie appropriate number of spaces are substituted. 
However, either bs_seq.count or cr_seq.count, should be nonzero (i.e., both should 
not be zero). 

tab_seq 

is the output character sequence to be substituted for a horizontal tab. If count is 
zero, the appropriate number of spaces is substituted. 

vt_seq 

is the output character sequence to be substituted for a vertical tab. If count is 
zero, no characters are substituted. 

ff_S«} 

is the output character sequence to be substituted for a formfeed. If count is zero, 
no characters are substitut€»d. 

printer_on 

is the character sequence to be used to implement the printer_on control operation. 
If count is zero, the function is not performed. 

printer_off 

is the character sequence to be used to implement the printer_off control operation. 
If count is zero, the function is not performed. 

red_ribbon_shift 

is the character sequence to be substituted for a red-ribbon-shift character. If count 
is zero, no characters are substituted. 
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black_ribbon_shif t 

is the character sequence to be substituted for a black_ribbon_shift character. If 
count is zero, no characters are substituted. 

end_of_page 

is the character sequence to be printed to indicate that a page of output is full. If 
count is zero, no additional characters are printed, and the cursor is left at the end 
of the last line. 

escape_length 

is the number of output escape sequences in each of the two escape arrays. 
not_edited_escapes 

is an array of escape sequences to be substituted for particular characters if the 
terminal is in "^edit^" mode. This array is indexed according to the indicator found 
in the corresponding output conversion table (see the description of the 
set_output_conversion order above). 

edited_escapes 

is an array of escape sequences to be used in edited mode. It is indexed in the 
same fashion as not_edited_escapes. 

input_escapes 

is a string of characters each of which forms an escape sequence when preceded by 
an escape character. 

input_results 

is a string of characters each of which is to replace the escape sequence consisting 
of an escape character and the character occupying the corresponding position in 
input_escapes. 

get_token_characters, set_token_characters 

changes the set of characters that are used by the video system input line editor to 
define a word for such requests as ESC DEL, The set of characters supplied in the 
structure replace the existing set of characters. The info_ptr points to the following 
structure (declared in window_control_info.incl.pll): 

del 1 token_characters__i nfo aligned based 

(token__characters_i nf o_ptr) , 
2 version char (8) , 

2 token_characters_count fixed bin, 
2 token characters cl^ar (128) unaligned; 



STRUCTURE ELEMENTS 



version 

is the version string for this structure. (Input) Its current value is 
token_characters_info_version_l, also declared in the include file. 
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token_characters_counL 

is the number of characters in the token_characters string. (Input) 

token_characters 

is a character string containing the new set of token characters. (Input) 

NOTES 

The set_token_characters and get_token_characters control orders are available from command_level 
and as active functions with the following io.call commands: 

io__call control wlndow__swi tch get_token_characters 

io_call control wi ndow__swi tch set__token_characters token__char_str ing 

where token_char_string is a character string containing the new set of token characters. 
get_token_character returns its result as a string if it was invoked as an active fimction, 
otherwise it prints out the token characters. 



get_editor_key_bindings 

returns a pointer to the line_editor_key_binding structure describing the key bindings. 
io_call support points out the pathname of each editor routine, listing only the names of 
builtin requests in capital letters, with the word "builtin" in parentheses. The control 
order prints or returns current information about the key bindings. Use the 
set_editor_key_bindings control order to change the bindings. This control order prints or 
returns current information about the key_bindings. Use the set_editor_key_bindings 
control order to change the bindings. 

The info_ptr points to the following structure (declared in window_control_info.incl.pll): 

del 1 get_edi tor_key_bindlngs_lnfo aligned based 

(get__ed i tor_key_b i nd I ng_i nf o__ptr) , 

2 version char (8) , 
2 flags, 

3 entire_state bit (1) unaligned, 

3 mbx bit (35) unaligned, 

2 key_binding_info_ptr ptr, 

2 ent I re_state_ptr ptr; 



STRUCTURE ELEMENTS 



version 

is get_editor_key_bindin&_info_version_l. (Input) 
entire_state 

is "l"b if the entire state is desired, "0"b if only information about certain 
keybindings is desired. (Input) 
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key_binding_inf o_ptr 

if entire_state = "0"b, then this points to a line_editoT_key_binding_structure. (Input) 

The bindings component of this structure is then filled in based upon the value of 
each key.sequence supplied. 

entire_state_ptr 

is set to point to the "state" of the key bindings, if entire_state = "l"b. (Output) 
This is suitable input to the set_editor_key_bindings control order. 

NOTES 

The get_editor_key_bindings control order is available from command level and as an active 
function with following io.call command: 

io_call control wi ndow_swi tch get__edi tor_key_bl ndi ngs 

The get_editor_key_bindings control order prints or returns information about a key binding. 
When you use it as an active function ^e information is returned in a form suitable as 
arguments to the set_editor„key_bindings control order. 

set_editor_key_bindings 

A line editor routine is bound to a sequence of keystrokes via the set_editor_key 
bindings control order. The sequence of characters that triggers an editor request may be 
of any length, with multiple-key sequences working like the Emacs prefix characters. 
This allows the use of terminal function keys (which often send three or more character 
sequences) to invoke line editor requests. More than one binding can be set in one 
invocation of this control order. 

The info_ptr points to the following structure (declared in window_control_info.incl.pll): 

del 1 set__edi tor_key_bindings__info aligned based 

(set_ed I tor_key_b i nd i ngs_l nf o_ptr) , 

2 version char (8) , 
2 flags, 

3 replace bit (1) unaligned, 

3 update bit (1) unaligned, 

3 pad bit (3^) unaligned. 
2 key_binding_info_ptr; 

STRUCTURE ELEMENTS 



version 

is the version of the structure. (Input) It must be set_editor_key_bindings_info_version_l. 
replace 

if "l"b then key_binding_info is considered to be returned by a previous 

get_editor_key_bindinp operation with entiTe_state = "l"b and will be used to 
replace the keybinding state of the editor. (Input) 
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update 

if "l"b then key_binding_info_ptr is considered a pointer to a 
line_editor_key_binding_info structure, which will be used to update the keybinding 
state of the editor. (Input) 

Note: only one of replace and update may be true, but at least one of them must 
be true. 

key_binding_inf o_ptr 

is a pointer received from get_editor_key bindings operation or a pointer to a 
line_editor_key_binding_info structure, depending on the value of the replace and 
update flags. (Input) 

Notes on freeing: The video system's internal data structures are freed at the following 
times: video system revocation and when a set_editor_key_bindings control order with 
replace = "l"b is done. 

NOTES 

The set_editor_key_bindings control order is available from command level and as an active 
function with the following io_call command: 

io_can control wi ndow__swi tch set_edi tor_key__bindings key_sequencel 
{user_routinel} {control__args 1} ... key__sequenceN 
{user_rout i neN} {contro1_args 1} {control_argsN} 

where user_routine is the name of a user-written editor request 

control args are: 

-external user__rout I ne 

-bull tin bui 1 tin_request_name 

-numarg_act i on numarg_ac t i on_name 

The line_editor_key_bindings_info structure is described in Section 7. 

At least one user_routine or one of -external /-builtin must be specified for each key 
sequence, with the rightmost editor request specifier taking precedence (for example, io 
control window_switch set__editor_key_binings foo -builtin FORWARD_word,) will bind control 
-a to the forward word builtin, not the user routine foo. 



numarg_action_name 

the type of automatic numeric argument to be taken when the editor routine is invoked, 
must be one of the following and can only be given for external editor routines 

REPEAT 

(the default is PASS). This can be entered in upper or lower case. Call the user routine | 
n times, where n is the numeric argument supplied by the user. 
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REJECT 

ring the tenninal bell and don*t call the user routine if a numeric argument is given. 
PASS 

pass any numeric argument to the user routine, without any other action. 
IGNORE 

same as PASS but implies the user routine will not make use of the numeric argument 
-name STR 

specifies the name of the editor command being assigned to the key. If this is the null 
string, then a default name is used (for builtins this is the name of the builtin, otherwise 
it is segnameSentrypoint). STR must be quoted if it contains whitespace. 

-description STR 

specifies a description string to be associated with the key binding. If this is the null 

string, a default description is used. The defaults can be found in the include file 

window_editor_values.incl.pll. STR must be quoted if it contains whitespace. 

-info_pathname PATH 

specifies an info segment pathname to be associated with this key binding. This info 
segment is expected to have more information about the editor_routine. If this is not 
specified, it defaults to >doc>info>video_editing.gi.info if -builtin, otherwise no info 
s^ment is associated with the key. The info suffix is assumed on PATH. 

MODES OPERATION 

The modes operation is supported by window_io_. The recognized modes are listed below. 
Some modes have a complement indicated by the circumflex character (^) that turns the mode 
off (e.g. '^more). For these modes, the complement is displayed with that mode. Some modes 
specify a parameter that can take on a value (e.g. more_mode). These modes are specified as 
MODE" VALUE, where MODE is the name of the mode and VALUE is the value it is to be 
set to. Parameterized modes are indicated by the notation (P) in the following description: 

more, '^more 

Turns MORE processing on. Default is on. If ^pl is set before you invoke the video 
system, ^more will be set when you invoke the video system. 

more_mode = STR 

controls behavior when the window is filled. The value for STR may be one of the 
following: 

clear 

the window is cleared, and output starts at the home position. 

fold 

output begins at tjie first line and moves down the screen a line at a time replacing 
existing text with new text Prompts for a MORE response when it is about to 
overwrite the first line written since the last read or MORE break. 
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scroll 

lines are scrolled off the top of the window, and new lines are printed in the space 
that is cleared at the bottom of the screen. This is the default for full width 
windows on all terminals capable of scrolling. 

wrap 

output begins at the first line and moves down the screen a line at a time replacing 
existing text with new text Prompts for a MORE response at the bottom of every 
window of output This is the default for all terminals that are incapable of 
scrolling or when using partial width windows. 

vertsp, ''^vertsp 

is only effective when more mode is on. When vertsp mode is on, output of a FF 
or VT will cause an immediate MORE query. When you invoke the video system, it 
copies the current setting of this mode before attaching the window_io_ module. The 
default is -^vertsp. 

rawo, '^rawo 

causes characters to be output with no processing whatsoever. The result of output in 
this mode is undefined. 

can, '^can 

causes input lines to be canonicalized before they are returned. When you invoke the 
video system, it copies the current setting of this mode before attaching the 
window_io_ module. The default is on. 

ctLchar, '^ctLchar 

specifies that ASCII control characters that do not cause newline or linefeed motion 
are to be accepted as input except for the NUL character. If the mode is off all 
such characters are discarded. When you invoke the video system, it copies the 
current setting of this mode before attaching the window_io_ module. The default is 
off. 

edited, '^edited 

suppresses printing of characters for which there is no defined Multics equivalent on 
the device referenced. If edited mode is off, the 9-bit octal representation of the 
character is printed. When yoU invoke the video system, it copies the current setting 
of this mode before attaching the window_io_ module. The default is off. 

erkl, '^erkl 

controls the editing functions of get_line. When you invoke the video system, it 
copies the current setting of this mode before attaching the window_io_ module. The 
default is on, which allows erase and kill processing and the additional line editor 
functions. 
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esc, '^esc 

controls input escape processing. When you invoke the video system, it copies the 
current setting of this mode before attaching the window_io_ module. The default is 
on. 

rawi, '^rawi 

acts as a master control for can, erkl, and esc. If this mode is on, none of the 
input conventions are provided. The default is on. 

11 = STR 

is the width of the window, in characters, and it can only be changed with the 
set_window_info control operation. 

pi = STR 

is the height of the window (i.e., number of lines), and it can only be changed with 
the set_window_info control operation. 

red, ^red 

controls interpretation of red shift and black shift characters on output. When you 
invoke the video system, it copies the current setting of this mode before attaching 
the window_io_ module. The default is '^red, which ignores them. In red mode, the 
character sequence given in the TTF is output The effect is undefined and 
terminal-specific. In some cases, "red shifted" output appears in inverse video, but 
this is not guaranteed. 

CONTROL OPERATIONS FROM COMMAND LEVEL 

Those control operations which require no info_ptr and those additional orders described 
above may be performed from command level using the io_call command, as follows: 

io call control switch name control order 



ARGUMENTS 

switch_name 

is the name of the I/O switch. 

control_order 

can be any control order described above under "Control Operation" that can accept a 
null info_ptr. 
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FORTRAN INTERFACE 



This section contains descriptions of the FORTRAN subroutine interface to the menu 
and video software. Two sample FORTRAN programs are provided that illustrate menu 
creation using automatic window management, and the FORTRAN video interface capabilities. 



In the FORTRAN environment, window management can be performed automatically. By 
using arguments to the FORTRAN window management functions ft_menu_$initl, ft_menu_$init2, 
and ft_menu_$terminate, applications that do not require sophisticated window management 
can employ automatic window management. When using automatic window management, your 
application works in two-window mode: the window in which the menu is displayed and the 
user i/o window. 



If your application requires greater window management capabilities, the menu interface 
capability lets you build menu applications using the ft_window_$create, ft_window_$destroy, 
ft_window_$clear, and ft_window_$change capabilities. 



Of course, FORTRAN applications, can still use command or PL/1 video management 
capabilities. 



Note that it is not possible to call the ft_menu_ routines with both ANSI77 and 
ANSI66 character strings. Currently, only ANSI77 character strings are allowed. 
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Name: ft__menu 

The ft_menu_ subroutine allows a FORTRAN program to use the Multics menu facility 
(menu_). Through ft_menu_ a FORTRAN program may create a menu object, display the 
menu, and get a user-entered selection from a menu. Once a menu object has been created, 
the FORTRAN program can use this menu object by referencing it via a menu-id returned to 
the caller when the menu object was created or when a stored menu object was retrieved. 

The functionality available is provided through the various entry points defined below. Also 
refer to the FORTRAN include file at the end of this section. 



Entry: ft menu__$create 

Utilized to create a menu object It returns a menu identifier (menu_id) which is 
subsequently used to reference the menu object 

USAGE 



declarations: 



character*nl 
character*n2 
character*n3 
character*] 
character*] 
i nteger 
integer 
i nteger 
i nteger 



choices (ml) 
headers (m2) 
trai lers (in3) 
keys (m4) 
pad__char 
menu_f ormat (6) 
menu_needs (3) 
menu_id 
code 



call ft_menu_$ create (choices, headers, trailers, pad_char, menu_f ormat , 
key, menu_needs, menu_id, code) 



STRUCTURE ELEMENTS 



choices 

is an array of character variables which are the text of the options that the user wishes 
to display in the menu. (Input) nl is the length, in characters, of the longest character 
string comprising the text of an option, ml is the extent of the array, i.e., the number 
of options in the menu being described. This array must be at least of extent 1. 
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headers 

is an array of character variables to be displayed at the top of the menu. (Input) nl is 
the length, in characters, of the longest header specified. in2 is the extent of the array, 
i.e., the number of headers (lines) desired. At least one header must be specified (if the 
first variable is set to blanks, no headers will be used). 

trailers 

is an array of trailers (displayed immediately below the menu). (Input) n3, mS, are 
analogous to n2, ml respectively. 

menu_format 

is an array, which specifies the format of the menu being created. (Input) Prior to 
calling this entry point, the FORTRAN programmer is responsible for setting the 
following variables: 

menu__format (menu_version) - version number of menu_ 

(currently, only version 1 is defined). 
menu_f ormat (max_wi dth) = maximum widtii of the window 

on which the menu will be displayed. 
menu__format (max_heigth) = maximum height of window 

on which menu is to be displayed. 
menu_f ormat (no_of_columns) = number of columns to be used 

by the menu manager to display the options. 
menu_f ormat (center_headers) - 0 or 1 ; 0 = no, 1 = yes. 
menu_f ormat (center__trai lers) = 0 or 1 ; 0 = no, 1 = yes. 



pad_char 

is the character that the menu facility will display at the right and left of a centered 
header or trailer to fill out the line. (Input) 

keys 

is an array (maximum value of m4 is 61) that identifies the keystroke to be associated 
with each choice. (Input) This array must be at least as long as the number of choices 
in the menu. Each element in the array must be unique. 

menu_needs 

an array that contains menu related information on successful execution of call. (Output) 
Returned information: 

menu_needs (1ines__needed) the number of lines required 

to display the menu. 
menu_needs (width_needed) the number of columns required 

to display the menu. 
menu_needs (no_of__options) the number of options defined 

in the menu. 
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menu_id 

the menu identifier (i.e., the menu object "identifier"). (Output) It must not be altered 
in any way by the application program. 

code 

return code. (Output) (See Appendix B.) 
Entry: ft ^menu^$delete 

Deletes a menu object from a given value segment (See ft_menu_$store.) 
USAGE 

declarations: 

character*] 68 dir_name 
character*32 entry_name 
character*32 menu__name 
i nteger code 

call f t_menu_$del ete (di rename, entry_name, menu_name, code) 
STRUCTURE ELEMENTS 



dir_name 

pathname of the directory containing the menu object (Input) 
entry_name 

entry name of value segment containing the menu object. (Input) The suffix "value" need 
not be specified. 

menu_name 

name used to identify the menu object when the menu object was stored. (Input) 

code 

return code. (Output) (See Appendix B.) 



Entry: ft menu $describe 

Returns information about a menu object It returns the number of options in the menu, the 
number of lines and number of columns required to display the menu. It is primarily used 
to determine if the menu can be displayed in a given window. 
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USAGE 

declarations: 

Integer menu__id 

i nteger menu_needs (3) 

integer code 

call f t_menu_$descr Ibe (menu_id, menu_needs, code) 



STRUCTURE ELEMENTS 



menu_id 

the menu identifier returned by ft_menu_$create or ft_menu_$retrieve. (Input) 
menu_needs 

an array into which menu related information is returned. (Output) 
Returned information: 

menu_needs (1 i nes_needed) the number of lines required 

to display the menu. 

menu_needs (width_needed) the number of columns needed 

to display the menu. 

menu_needs (no_of_opt i ons) the number of options defined 

in the menu. 



code 

return code. (Output) (See Appendix B.) 



Entry: ft menu ^$destroy 

Invoked to delete a menu object from storage. (Not to be confused with ft_menu_$delete, 

which deletes the menu object from a value segment) Deleting the menu object has no 
effect on the screen contents. 

USAGE 

declarations: 

integer menu_id 
integer code 

call f t__menu_$destroy (menu__id, code); 
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STRUCTURE ELEMENTS 



menu_id 

menu identifier returned by ft_menu_$create or ft_menu_$retrieve. (Input/Output) Set to 
an invalid value on return to prevent the old menu_id from being accidentally used. 

code 

return code. (Output) (See Appendix B.) 



Entry: ft menu ^(display 

Invoked to display a menu in a given window. 
USAGE 

declarations: 

integer window_id 
integer menu__id 
integer code 

call ft_menu_$di splay (window__id, menu__id, code) 



STRUCTURE ELEMENTS 



window_id 

a window identifier returned by ft_window_$create. (Input) If usage_mode = 0 this 
argument will be ignored (see ft_menu_$init2). 

menu_id 

menu identifier returned when the menu object was created or retrieved. (Input) 

code 

return code. (Output) (See Appendix B.) 



Entry: ft menu„$get_choice 

Returns the choice made by the user, i.e., an integer representing either the menu item 
chosen or the function key (or its equivalent escape sequence) entered. 
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USAGE 

declarations: 

character*nl funct ion_key__info 
integer window__id 
integer menu_id 
integer fkeys 
integer selection 
i nteger code 

call f t_menu_$get_choi ce (window_id, menu__id, f unct i on_key_i nf o, fkeys, 
selection, code) 

STRUCTURE ELEMENTS 



wmdow_id 

a window identifier returned by ft_window_$create. (Input) If usage_mode = 0 this 
argument will be ignored, (see ft_menu_$init2) 

menu_id 

menu identifier returned by ft_menu_$create or ft_menu_$retrieve. (Input) 
f unction_key_inf o 

a character variable (nl as required) used to specify the role of function keys (if they 
exist for the terminal being used) or an equivalent set of escape sequences if the 
terminal does not have function keys or not the function keys required by the 
application. (Input) The objective is to let the application use the terminal's function 
keys if possible, else specify key sequences to be used to simulate function keys. Each 
character in the string corresponds to one function key. If the character is a space, then 
it is not relevant if the corresponding function key exists or not. If the character is not 
a space, that character will be used to simulate a function key if the terminal does not 
have function keys. If the terminal does not have a function key for every non-space 
character in the string, then function keys will be simulated. Thus, the string " ?p q" 
means that the caller does not care whether the terminal has function key 0 or 3, but | 
the caller does wish to use function keys 1,2, and 4. If any of these 3 function keys is 
not present on the terminal, then esc-? will substitute for Fl, esc-p will substitute for 
F2, and esc-q will substitute for F4. 

fkeys 

if fkeys = 1 user entered a function key or escape sequence if fkeys = 0 user selected 
an option (Output) 

selection 

is an integer representing the choice made by the user. (Output) If the user has chosen 
an option, it is a number between 1 and the highest defined option. If the user has 
entered a function key, or escape sequence simulating a function key, it is the number 
associated with the function key. 
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code 

return code. (Output) (See Appendix B.) 
Entries: ft menu ^Sinitl, ft_menii_$iiiit2 

These must be the first calls made to the menu manager. They set up the necessary 
environment for the menu application and return information concerning the user i/o window. 

USAGE 

declarations: 

integer code 

i nteger usage_mode 

call f t_menu_$ i ni tl () 

cal 1 f t_menu_$ini t2 (usage_mode,user_wi ndow_l i nes,user_window_columns, 
user_wi ndow_id,code) 

STRUCTURE ELEMENTS 



usage_mode 

usage_mode = 0 means that the caller does not wish to do any window management at 
all. (Input) When he/she wishes to display a menu, the window required will be 
automatically created. This means that the application will operate in a two window 
mode, the window containing the menu, and tie user_io window. Both windows will be 
managed automatically for the user. If the user specifies this mode, all calls to the 
ft_window_ subroutine will be ignored and will return an appropriate error code. See 
Error Code Handling (Appendix B), below. All calls to the ft_menu_ subroutine that 
require a window identifier will ignore the user provided window_id. 

usage_mode = 1 means that the user wishes to define the number and characteristics of 
the windows to be used in the application. Thus, calls to ft_window_ will be supported 
and, for the entry points of ft_menu_ that require a window identifier, the caller must 
use a legal window_id (returned by ft_window_$create). 

user_window_lines 

the number of lines (rows) in the user i/o window at the time the user invokes 
ft_menu_$init (which must be the first call to the menu manager in the application). 
(Output) Undefined if usage_mode = 0. 

user_window_colunms 

the number of columns of the user i/o window when ft_menu_$init invoked. (Output) 
Undefined if usage_mode = 0. 

user_window_id 

window identifier of the user i/o window. (Output) Undefined if usage_mode = 0. 

code 

return code (See Appendix B.) (Output) 
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Entry: ft menu ^Slist 

Used to list the menu object(s) stored in value s^ment The names selected are those that 
match a user provided string. 

USAGE 



declarations: 

character*l68 dir_name 
character*32 names__array (ml) 
character*32 entry_name 
character''<32 match__str i ng 
integer no__of_matches 
integer code 

call f t__menu_$l ist {dlr_name, entry_name, match_str i ng, no__of_matches, 
names__array , code) 



STRUCTURE ELEMENTS 



dir_name 

pathname of directory containing Uie menu object (Input) 
entry_name 

entry name of value segment containing the menu object. (Input) The suffix "value" need 
not be specified. 

match_string 

a character variable that is to be used as the selection criteria to determine what menu 
object, if any, is contained in the specified value segment that match (or contain) this 
string. (Input) If set to space(s), all names returned. 

no_of_matches 

the number of matches found. (Output) If none, then is is 0. 



names_array 

an array, of extent ml. (Output) The user should insure that ml is sufficiently large to 
contain all matches that may be found. Contains the names of all menu objects, in the 
specified value segment, that match the character string match^string. 



code 

return code. (Output) (See Appendix B.) 
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Entry: ft_menu^$retrieve 

Used to retrieve a menu object previously stored via the ft_menu_$store. Once retrieved, the 
user can reference the menu object via the menu identifier (menu.id). 

USAGE 

declarations: 

character* 168 dir_name 
character*32 entry__name 
character*32 inenu_name 
integer menu_id 
integer code 

call f t__menu_$retr ieve (dir_name, entry_name, menu_name, menu_id, code) 
STRUCTURE ELEMENTS 



dir_name 

pathname of the directory containing the menu object (Input) 
entry_name 

entry name of value segment containing menu object (Input) The suffix "value" need not 
be specified. 

menu_name 

name of the menu object used when the object was stored. (Input) 
menu_id 

is the menu id returned by the call. (Output) It is used as the menu object identifier. 

code 

return code. (Output) (See Appendix B.) 
Entry: ft menu ^$store 

Used to store a menu object in a specified value segment 
USAGE 

declarations: 

character*lS8 dir_name 

character*32 entry__name 

character*32 menu_name 

nteger create__seg 

nteger menu_id 

nteger code 
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call ft__menu_$ store (di r_name,entry_name, menu__name, create_seg, 
menu_id, code) 

STRUCTURE ELEMENTS 



dir_name 

pathname of directory into which the menu object is to be placed. (Input) 
entry_name 

entry name of value segment into which the menu object is to be placed. (Input) The 
suffix "value" need not be specified. 

menu_name 

it is the name to be assigned to the stored menu object. (Input) 
create_seg 

create_seg = 0 means do not store if value segment identified by entry_name does not 
already exist (Input) 

create_seg = 1 means create value segment, if it does not already exist, and store menu 
object in it 

menu_id 

it is the menu object identifier returned when ft_menu_$create or ft_menu_$retrieve was 
called. (Input) 

code 

return code. (Output) (See Appendix B.) 
Entry: ft menu ^Sterminate 

Must be the last call to the menu manager in the menu application. It will remove the 
special environment created by ft_menu_$initl and ft_menu_$init2. 

USAGE 

declarations: none 

call ft_menu $ terminate () 
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FORTRAN INCLUDE FILE 

This include file contains the following declarations: 

external ft__menu_$ create (descriptors) 

external f t__menu_$delete (descriptors) 

external f t_menu_$descr Ibe (descriptors) 

external f t_menu_$destroy (descriptors) 

external ft__menu_$di splay (descriptors) 

external f t_menu_$get_choice (descriptors) 

external f t_menu_$i ni tl (descriptors) 

external f t_tnenu_$ i ni t2 (descriptors) 

external f t_menu_$ 1 i st (descriptors) 

external f t_menu__$retr i eve (descriptors) 

external ft_menu__$ store (descriptors) 

external f t_wi ndow_$ change (descriptors) 

external f t_wi ndow__$create (descriptors) 

external f t_wi ndow_$destroy (descriptors) 



integer menu_vers i on 

integer max_width 

integer max_height 

integer no_of_col umns 

i nteger 1 i nes_needed 

integer width_needed 

i nteger no_of _opt i ons 

integer center_headers 

integer center_trai lers 

integer user_wi ndow_id 

integer user_wi ndow__l i nes 

integer user_wi ndow_columns 

parameter (menu_vers i on = 1) 

parameter (max_width = 2) 

parameter (max_height = 3) 

parameter (no__of _co 1 umns = h) 

parameter (center_headers = 5) 

parameter (center_tra i 1 ers = 6) 

parameter (1 i nes_needed = 1) 

parameter (width_needed = 2) 

parameter (no_of_options = 3) 
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Name: ft_„wmdow„ 

This is the basic video interface subroutine to be used by FORTRAN to create/destroy/change 
windows. (This subroutine should not be called if usage_mode = 0 (see ft_menu_$init2)). 

Its facilities are available through the following entry points. 



Entry: ft__window__$change 

This entry point is used to change the size of an existing window. The size of a window can 
always be "shrunk", however it can be increased only it does not overlap with another 
defined window. (This entry point should not be called if usage_mode = 0 (see 
f t_menu_$init2).) 

USAGE 

declarations: 

integer window_id 

i nteger f i rst_l i ne 

integer height 

i nteger code 

call ft_wi ndow_$ change (window_id, first_line, heigth, code) 



STRUCTURE ELEMENTS 



window_id 

window identifier returned by ft_window_$create (or by ft_menu_$init in the case of the 
user i/o window). (Input) 

first_line 

new first line number for the window being changed. (Input) Positive integer, 
height 

new height for the window being changed. (Input) Positive integer. 

code 

return code. (Output) (See Appendix B.) 
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Entry: ft ^window_$clear__window 

Used to clear a specified window. 
USAGE 

declarations: 

integer window__id 
integer code 

call f t_wi ndow__$clear_wi ndow (window__id, code) 
STRUCTURE ELEMENTS 



window_id 

The window identifier (returned by f t_window_$create) of the window to be cleared. 
(Input) 

code 

return code. (Output) (See Appendix B.) 
Entry: ft ^window_$create 

Used to create a new window on the terminal screen. (This entry point should not be called 
if usage_mode = 0.) (see ft_menu_$init2) 

USAGE 

declarations: 

character*32 switch_name 
integer window_id 
i nteger f i rst__l i ne 

integer height 
integer code 

call f t_wi ndow_$ create (first_line, height, swi tch__name, window_ld, 
code) 

STRUCTURE ELEMENTS 



first_line 

is the line number where the window is to start (Input) 
height 

the number of lines used by the window, i,e,, its height (Input) 
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switch_name 

the name that the caller wishes to associate with the switch. (Input) (The caller may use 
the switch name, for example, in the FORTRAN "open" statement) 

window_id 

the returned id of the window just created. (Output) It must not be altered in any way 
by the application program. 

code 

return code. (Output) (See Appendix B.) 



Entry: ft wmdow__$destroy 

Used to destroy a previously created window. (This entry point should not be called if 
usage_mode = 0 (see ft_menu_$init2).) 

USAGE 

declarations: 

integer wlndow_id 
integer code 

call f t_wi ndow_$destroy (window_id, code) 



STRUCTURE ELEMENTS 



window_id 

window identifier (returned by the ft_window_$create). (Input/ Output) It is reset to an 
illegal value by this call. 

code 

return code. (Output) (See Appendix B.) 
FORTRAN MENU APPLICATION EXAMPLES 

In the following two FORTRAN examples, a "Message" menu application is created that 
allows you to display, print, discard, or forward messages. Example 1 is a simple FORTRAN 
program that interfaces with the Multics menu manager via the ft_menu_ routine. Note in 
Example 1 that window management functions are called automatically through arguments in 
the ft_menu_$init2 subroutine. 

Example 2 is a FORTRAN program that interfaces with the Multics menu manager through 
ft_menu_routine; in example 2, however, window management functions are performed by the 
ft_window_ routine. 
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EXAMPLE 1: 



In this example, all window management is done automatically. 

subroutine tes teasel () 

% include f t_menu__dc 1 s 

external f t_menu_$ i n i t 1 (descriptors) 
external f t_menu_$ i ni t2 (descriptors) 
character*15 choices (6) 



character*12 


{leaders (1) 


character*27 


trai lers (1) 


character*l 


keys (6) 


character*l68 


d i r_name 


character*32 


entry_name 


character*32 


menu_name 


character*12 


f unct i on_lcey_i nf o 


character*32 


switch name 


character*9 


ME 


i nteger 


create_seg 


integer 


no_of_matches 


i nteger 


wi ndow_id 


i nteger 


f keys 


i nteger 


selection 


i nteger 


usage_mode 


i nteger 


menu_f ormat (6) 


i nteger 


menu_needs (3) 


i nteger 


menu_id 


i nteger 


code 


i nteger 


zero 



external com_err_ (descriptors) 

integer too_f ew__keys 

integer bad_arg 

integer keys_not__unique 



ME = "testcasel" 
zero = 0 



choices (1) = "Display Message" 
choices (2) = "Print Message" 
choices (3) = "Discard Message" 
choices (4) = "Forward Message" 
choices (5) = "Reply Message" 
choices (6) = "List Messages" 
headers (1) = "READ MAIL" 

trai lers (1) = "Press Fl (or esc-q) to quit" 
keys (1) = "1" 
keys (2) = "2" 
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keys (3) - "3" 
keys (4) - "k" 
keys (5) = "5" 
keys (6) = "6" 
pad_ctiar = 

menu_format (menu_version) = 1 
menu_f ormat (max_width) - 79 
menu_format (max__height) = 10 
menu_format (no__of_columns) - 2 
me nu__f ormat (center_headers) = 1 
menu_f ormat (center trailers) = 1 



code = 0 

usage_mode = 0 ! Window management will be done automatically 
! by the system, i.e., usage_mode is set to 0. 
! by the system, i.e., usage_mode is set to 0. 

call f t_menu_$ i n i 1 1 () 

cal 1 f t_menu_$ i ni t2 (usage_mode,user_wi ndow_l I nes,user_wi ndow_columns, 

user_wl ndow_ld, code) 
! Calling f t_menu_$ 1 ni t MUST 

! be the first call to ft_menu_ In the program, 
if (code .eq. zero) go to 5 

call com_err_ (code, ME, " (calling f t_menu_$ i ni t2) ") 

print, "Unable to set up the appropriate environment for the application." 
go to 999 

c The following calls to cv_error_$name are used retrieve and store 
c the error codes associated with certain errors of interest returned 
c by calls to the menu manager or the system. 

5 call cv_error__$name ("error_table_$bad_arg", bad_arg, code) 
if (code .eq. zero) go to 10 

call com__err_ (code, ME, "error_tabl e_$bad__arg") 
go to 999 

10 call cv_error_$name ("menu_et_$too_few_keys", too__few_keys,code) 
if (code .eq. zero) go to 20 

call com_err_ (code, ME, "menu_et__$too_f ew_keys") 
go to 999 

20 call cv_error_$name ("menu_et_$keys_not_unique" , keys__not_unlque, code) 
if (code .eq. zero) go to 40 

call com__err_ (code, HE, "menu_et_$keys__not_unique") 
go to 999~ 

kO call ft_menu__$ create (choices, headers, trai lers,pad_char,menu_format, 

6 keys,menu__needs,menu_id,code) 

c This call creates the menu object and returns the menu object identifier, 
c "menu id". 
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if (code .eq. zero) go to kS 

call com_err_ (code, ME, " (calling f t_menu_$ceate) ") 
print, '-'The menu could not be created." 
go to 999 

c The created menu is now stored for future use. 

45 dlr_name = ">udd>m>ri" ! pathname of directory 

entry_name = "menus_seg" ! entry name of "value" segment 

menu_name = "f t_read_mai l_menu" ! name of menu 

create_seg = 1 ! create "value" seg if it does not already exist. 

call ft__menu_$ store (dir_name, entry_name, menu_name, 

create__seg, menu__id, code) 
if (code .eq. zero) go to 30 



call com_err_ (code, ME, " (calling f t_menu__$store) ") 

print, "The menu could not be stored." 

go to 999 
50 window_id = 0 

call ft_menu__$di splay (window_id, menu__ id, code) ! This call displays 

! the menu in its own window at top of screen. Since the usage_mode 

! was set to 0, the program does not have to create the window 

! before calling f t__menu_$di splay . The window_id argument is ignored. 

if (code .eq. zero) go to 60 

call com_err_ (code, ME, " (calling f t_menu_$di spl ay) ") 
print, "The menu could not be displayed." 
go to 999 

60 f unct ion_key_i nf o = "q" ! Defines the function key requirements, i .e, 

! if the terminal has function key 1 (Fl) then Fl will be used 
! to "quit", otherwise "esc_q" will be used to "quit". 

61 cal 1 f t__menu_$get_choi ce (window_id,menu__id,function_key_info,f keys, 
&' select ion, code) 

c This call accepts the user input from the menu. On return, the variable 

c "selection" will contain a number (1, 2, 3 * or k) representing the option 

c chosen by user. 

c Note: if the user entered anything other than 1 or 2 or 3 or 4 

c the terminal "beeped", and the user input was ignored, 

c Since usage_mode is 0, the window_id argument is ignored. 

if (code .eq. zero) go to 90 

if (code .ne. too_f ew_keys) go to 70 

call com_err_ (0, ME, "Number of keys less than number of options.") 
go to 999 

70 if (code .ne. keys_not_uni,que) go to 80 

call com_err__ (0, ME, "Option keys not unique.") 
go to 999 
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80 call com_err__ (code, ME, " (calling f t_menu_$get__choice) . 

An Internal programming error has occurred.") 

go to 999 

90 if (fkeys .eq. zero) go to 110 
if (fkeys .eq. 1) go to TOO 

print, "An internal program error has occurred. Quitting." 

go to 999 
100 if (selection .ne. 1) go to 6 1 

print, "You entered ""pi"" or ""esc q"". Quitting." 

go to 999 
110 print 103. select ion 
103 format ("You selected option "il) 

go to 50 

999 call f t_menu_$termi nate 0 
return 
end 



EXAMPLE 2: 

In this example, FORTRAN interfaces with the Multics menu manager and the Multics 
window manager via the ft_menu_ and ft_window_ subroutines. 

subroutine testcase2 () 

% include f t_menu__dcl s 

external f t_menu_$ i ni tl (descriptors) 

external f t_menu_$ i n i t2 (descr i ptors) 

external f t_window_$clear_window (descriptors) 

character*9 cho i ces_one (2) 

character5»2 1 choices__three (ii) 

character*21 headers (1) 

character*^9 trailers (1) 

character*l keys (6) 

character*l68 dir__name 

character*32 entry_name 

character*'«32 menu_name 

character*! 2 f unct ion_key_i nfo 

character*32 match_string 

character''«32 names__array (10) 

character><32 switch__name 

character*9 ME 

integer create_seg 

integer no_of_matches 

integer window_idl 

integer window__id2 

integer fkeys 

integer selection 

i nteger usage_mode 
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i nteger menu_f ormat (6) 

i nteger menu_needs__one (3) 

i nteger menu_needs_two (3) 

integer menu_needs_three (3) 

integer curr_wi ndow_id 

integer menu_idl 

integer menu_id2 

integer menu_id3 

integer code 

integer zero 

external com_err__(descr iptors) 

integer bad_wi ndow_id 

integer nonexistent_window 

integer i nsuf f__room__f or__wi ndow 



ME = "testcase2" 
zero = 0 



Choi ces_one (1) = "Read Mail" 

Choi ces^one (2) = "Send Mail" 

Choi ces_three (1) = "Send New Messsage" 

choi ces_three (2) = "Send Deferred f\^ssage" 

choi ces_three (3) = "Print Sent Message" 

choi ces_three (4) = "Save Sent Message" 

trailers (1)= "Fl (or esc-q) = quit ; F2 (or esc-f) = first menu 

keys(l) = "1" 

keys (2) = "2" 

keys (3) = "3" 

k-eys(4) = "1*" 

keys (5) = "5" 

keys (6) = "6" 

pad_char = 

menu_format (menu_version) = 1 
menu_format (max__width) = 79 
menu_f ormat (max_hei ght) = 8 
menu_f ormat (no_of_col umns) = 2 
menu_f ormat (center_headers) = 1 
menu format (center trailers) = 1 



code = 0 

call f t_menu__$ i n i 1 1 () 

usage_mode - 1 Window management will be done by user 
cal 1 f t_menu_$ i ni t2 (usage_mode, user_wi ndow_l i nes , user_wi ndow_col umns, 
& user_wi ndow_id,code) Calling f t_menu__$ i ni t MUST be the 

first call to ft_menu_ in the program. 
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if (code .eq. 0) go to 5 

call com_err__ (code, ME, (calling f t_menu_$ 1 ni t) ") 
print, "Unable to set up tlie appropriate environment for the 
& application." 
go to 999 

c The following calls to cv_error_$name are used retrieve and store 

c the error codes associated with certain errors of interest returned 
c by calls to the menu manager or the system. 

5 call cv_error_$name ("video_et_$bad_wi ndow_id", bad__wi ndow__id, code) 
if (code .eq. zero) go to 10 

call com__err_ (code, ME, "video_et__$bad_wi ndow__id") 
go to 999 

10 call cv__error_$name ("video_et_$nonexistent_window", 

nonexi s ten t_window, code) 
if (code .eq. zero) go to 20 

call com_err_ (code, ME, "video_et_$nonexi stent_wi ndow") 
go to 999 

20 call cv_error_$name ("video_et_$ i nsuf f_room_f or_wi ndow" , 

6 i nsuf f_room__for_wi ndow, code) 
if (code ,eq. zero) go to kO 

call com__^err_ (code, ME, "vi deo_et_$ i nsuf f_room_for_wi ndow") 
go to 999 

c Create first menu 

kO headers (1) = "MULTICS MAIL" 

cal 1 ft_menu_$ create (cho ices_one, headers, trai lers,pad_char ,menu_format, 
& keys,menu_needs_one,menu_idl ,code) 

c This call creates the menu object and returns the menu object identifier, 
c This menu is referenced by menu__idl. 

if (code .eq. 0) go to 1*1 

call com_err_ (code, ME, " (calling f t_menu_$ceate) ") 
print, "The first menu could not be created." 
go to 999 

c For the second menu use a menu object which was stored in a "value" seg. 
c First determine if menu object exists. 

41 dir_name = ">udd>m>ri" 
entry_name = "menus_seg" 
match_string = "f t_read_mai l__menu" 

cal 1 f t_menu_$l ist (dir_name,entry__name,match_str ing,no_of_matches, 
& names_ar ray, code) 

if (code .eq. zero) go to k2 

call com__err__ (code, ME, " (calling f t_menu_$l i st) ") 
go to 999 

k2 if (no_of__matches .eq. zero) then 
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print, "Stored menu not found." 
go to 999 
el se 

if (no_of_matches .eq. 1) go to 3 
print, "Internal error. Quitting." 
go to 999 
end i f 

c Retrieve stored menu. 

43 menu_name = "f t_read_mal l__menu" 

cal 1 f t__menu_$retr i eve (dl r__name,entry_name,menu__name,menu_ld2,code) 
if (code .eq. zero) go to kk 

call com_err_ (code, ME, " (calling f t_menu__$retr ieve) ") 
go to 999 

c Get attributes of retrieved menu. 

kk call f t_menu_$descr ibe (menu_ld2,menu__needs__two,code) 
if (code .eq. zero) go to kS 

call com_err_ (code, ME, " (calling f t_menu_$descr ibe) ") 
go to 999 

c Create third menu 

1»5 headers (1) « "SEND MAIL" 

call f t__menu_$create (cholces_three,headers, tral lers,pad_char, 
6 menu_f ormat , keys , menu_needs__three ,menu_i d3 $ code) 

if (code .eq. 0) go to 50 

call com_err_ (code, ME, " (calling f t_menu_$ceate) ") 
print, "The third menu could not be created." 
go to 999 

50 curr_window_ld = -1 "-i" indicates that there is no current menu 

being displayed; otherwise, curr_wi ndow__id 
contains the menu window id 

52 call change_menu (user_wi ndow_id,curr_wi ndow_id,menu_idl ,menu_needs__one, 
& user_window lines, window idl,code) 

if (code) 51,53.51 

51 call com_err_ (code,"change_menu"," I nternal error while changing menus.") 
go to 999 

53 call f t_wlndow__$clear_wlndow (user_wlndow_id, code) 

60 call get_choice (menu_idl ,window_idl ,f keys, selection, code) 

c This call accepts the user input from the menu. On return, the variable 

c "selection" will contain a number (0, 1, 2) representing the option or 

c the function key (or its equivalent escape sequence) entered by the user, 

c If fkeys = 1 then the user entered Fl or F2 (or esc-q or esc-f ) ; 
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c if Fl (or esc-q) was entered, then selection = 0 

c if F2 (or esc-f) was entered, then selection = 1 

c If fkeys = 0 then the user selected option: 

c if first option was chosen, then selection = 1 

c if second option was chosen, then selection = 2 

c Note: if the user entered anything other than Fl or F2 or 1 or 2 

c the terminal "beeped", and the user input was ignored. 

if (code .eq. zero) go to 70 

call com__err__ (0, "get__choice", "Internal program error 

while getting user choice") 

go to 999 

70 if (fkeys .eq. zero) go to 90 user selected an option 
if (fkeys .eq. 1) then 
go to 80 user entered function key 
else Something is wrong 

print, "An internal program error has occurred. Quitting." 
go to 999 
end i f 

Bo go to (81,82), selection 

call com_err_ (code, ME, "An internal program has occurred. Quitting.") 

go to 999 

81 print, "Exiting" (user has entered Fl or esc-q. Wants to exit) 
go to 999 

82 print, "You already are in the first menu." User want to go to 

f i rst menu 

go to 60 

90 go to (100,170), selection Display either "Read Mail" or "Send Mail 

menu 

call com_err_ (code, ME, "Internal program error. Quitting.") 
go to 999 

100 call change__menu (user_wi ndow_id,wi ndow_idl ,menu__id2,menu_needs_two, 
& user_wi ndow_l i nes, window_id2, code) 

if (code .eq. zero) go to 110 

call com_err_ (code, "change_menu", "Internal error occurred 

while switching menus") 

go to 999 

110 call get__choice (menu_id2, window_id2, fkeys, selection, code) 
if (code .ne. zero) then 

call com__err_ (code, "get_choice", "Internal error 

while getting user choice"). 

go to 999 
end i f 

go to (160, 150) . fkeys + 1 

call com_err_ (code, ME, "Internal program error. Quitting.") 
go to 999 

150 go to (151 » 152), selection user entered function key 
go to 110 

151 print, "Exiting at your request" 
go to 999 

152 curr window id = window id2 
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go to 52 
160 print 300, selection 

300 format ("You selected option "il) 
go to no 

c User chose "Send Mail" option 

170 call change__menu (user_wi ndow_id, window_idl ,menu_id3»menu_needs_three, 
& user_window lines, window id2,code) 

if (code) 171.180,171 

171 call com_err_ (code, "change_menu" , "Internal error 

while ciianging menus") 

go to 999 

180 call get_choice (menu_id3,wi ndow id2,f keys, select ion, code) 
if (code) 181,190.181 

181 call com_err__ (code, "get_choice", "Internal error 

while getting user choice") 

go to 999 
190 go to (210,200), fkeys + 1 

pr int, ." Internal error. Quitting" 
go to 999 

200 go to (201,202), selection 
go to 180 

201 print, "Exiting at your request." 
go to 888 

202 curr_wi ndow_i d = window_id2 
go to 52 

210 print 301, selection 

301 format ("You selected option "il) 
go to 180 

c Delete second menu from the value seg. 

888 call f t_menu_$del ete (di r_name,entry__name,menu__name,code) 
if (code .eq, zero) go to 999 

print, "Menu could not be deleted from value segment." 
999 call ft__menu_$ terminate 0 
return 
end 
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subroutine get_cholce (menu_id,wi ndow_id,f keys, select ion, code) 

external f t_menu_$get__choice (descriptors) 

character*2 function_key_info 

integer fkeys 

integer selection 

integer menu_id 

integer window_id 

i nteger code 

code = 0 



f unction_key_i nfo - "qf" Defines the function key requirements, i.e, 
if the terminal has function keys 1 and 2 (Fl and F2) then Fl 
will be used to "quit" and F2 to switch to the first menu, 
otherwise "esc__q" will be used to "quit" and "esc-f" to switch 
to the first menu 

call f t_menu_$get__cho i ce (w 1 ndow__i d , menu_ i d , f unc t i on_key_ info, fkeys , 
& select ion, code) 

return 
end 

subrout i ne change_menu (user__wi ndow_i d , cur r_wi ndow_i d ,menu_i d ,menu_needs , 

user_wi ndow_l i nes ,wi ndow_i d, code) 

external f t__wi ndow_$ change (descriptors) 

external f t__wi ndow_$ create (descriptors) 

external f t_wi ndow_$destroy (descriptors) 

external ft_menu_$di splay (descriptors) 

external com_err_ (descriptors) 



character"32 switch_name 



i nteger menu_needs (3) 

integer user_wi ndow_id 

integer user_wi ndow_columns 

i nteger user_wi ndow_l i nes 

integer curr_wi ndow_id 

integer menu_id 

integer window_id 

integer code 

integer first_line 

integer height 



parameter (1 ines_needed = 1) 
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c Destroy the current menu-window 

if (curr_window_id + 1) 90,100,90 
90 call ft wi ndow__$destroy (cur r_w i ndow_id, code) 
if (code) "999, 100,999 

c Change the size of the user i/o window to accomodate the new menu-window 

100 first_line = 1 + menu__needs (1 ines_needed) 

height - user_wi ndow__l i nes - menu_needs (1 i nes_needed) 

call ft_wi ndow_$ change (user__wi ndow_id, f i rst_l i ne, hei ght ,code) 

if (code) 999.110,999 

c Create window for new menu 

110 switch_name = "menu_wi ndow" 

call ft_window_$ create (1 ,menu_needs (1 i nes_needed) ,swi tch__name,wi ndow_id, 
& code) 

if (code) 999,120,999 

c Display the menu in the menu-window 

120 call ft_menu__$di splay (window_id,menu_id,code) 

999 return 
end 
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COBOL INTERFACE 



This section contains descriptions of the COBOL interface to the menu and video 
software. Two sample COBOL programs are provided that illustrate menu creation using 
automatic window management, and the COBOL video interface capabilities. 



In the COBOL environment, window management can be performed automatically. By 
using the COBOL window management functions cb_menu_$initl, cb_menu_$init2, and 
cb_menu_$terminate, applications that do not require sophisticated window management can 
employ automatic window management activity. When using automatic window management, 
your application works in two-window mode: the window in which the menu is displayed and 
the user_i/o window. 



If your application requires greater window management capabilities, the menu interface 
capability lets you build viable menu applications using the cb_window_$create, 
cb_window_$destroy, and cb_window_$change capabilities. 



Of course, COBOL applications can still use command or PL/1 video management 
capabiUties. 
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Name: cb ^menu_ 



The cb_menu_ subroutine allows a COBOL program to use the Multics menu facility (menu_). 
Through cb_menu_ a COBOL program may create a menu object, display the menu, and get 
a user-entered selection from a menu. Once a menu object has been created, the COBOL 
program can use this menu object by referencing it via a menu-id returned to the caller 
when the menu object was created or when a stored menu object was retrieved. 

The functionality available is provided through the various entry points described below. 



Entry: cb ^menu ^Screate 

Utilized to create a menu-object Returns a menu-id which may be subsequently used by 
other entry points. 

USAGE 



declarations: 



01 choices-table. 

02 choices PIC X(nl) OCCURS 
01 headers-table. 

02 headers PIC X (n2) OCCURS 
01 trailers-table. 

02 trailers PIC X (n3) OCCURS 
01 keys-table. 

02 keys PIC X(l) OCCURS 

01 menu-format. 

02 menu__version USAGE IS COMP-6 
02 constraints USAGE IS COMP-6 

03 max-width. 

03 max-height, 
02 no-of -columns USAGE IS COMP-6. 
02 flags. 

03 center-headers PIC 9(1). 

03 center-trailers PIC 9(1). 
02 pad-char PIC X(l) . 

01 menu-needs USAGE IS COMP-6. 
02 lines-needed. 
02 width-needed. 
02 no-of -opt ions. 

77 menu- id USAGE IS COMP-6. 
77 ret-code USAGE IS COMP-6. 



(ml) TIMES. 

(m2) TIMES. 

(m3) TIMES. 

(mM TIMES. 
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call "cb_menu_$create" USING choices-table, headers- table, 

trailers-table, menu-format, keys-table, menu-needs, menu-Id, 
ret-code. 

STRUCTURE ELEMENTS 



choices-table 

is a table of elementary data items which are the text of the options that the user 
wishes to display in the menu, nl is the length, in characters, of the longest character 
string comprising the text of an option, ml is \h& extent of the table, i.e., the number 
of options in the menu being described. This table must be at least of extent 1. 

headers-table 

is a table of elementary data items to be displayed at the top of the menu. (Input) n2 
is the length, in characters, of the longest header specified. m2 is the extent of the 
table, i.e., the nimiber of headers (lines) desired. At least one header must be specified 
(if the first header is set to space(s), no headers will be used). 

trailers-table 

is an table of trailers (displayed immediately below the menu). (Input) n3, m3, are 
analogous to n2, m2 respectively. 

menu-format 

is a group item defining the format of the menu being created. (Input) 
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In the CDBOL program the caller is responsible for setting the following elementary data 
items: 



menu-vers ion 

max-width 

max-hei ght 

no-of -columns 

center-headers 
center-trai lers 



the version number of the menu facility, 
(only version 1 is currently defined) 
maximum width of the window on which. the 
menu is to be displayed, 
maximum height of window on which the 
menu is to be displayed, 
number of columns to be used to display 
the options. 

0 or 1 ; 0 = no, 1 = yes . 

0 or 1 (same as center-headers) 



keys-table 

is a table (maximum value of m4 is 61) that identifies the keystroke to be associated 
with each choice. (Input) This table must be at least as long as the number of choices 
in the menu. Each element in the table must be unique. 

menu-needs 

a group item that contains menu related information on successful execution of call. 
(Output) 

Returned information: 

lines-needed the number of lines required 

to display the menu, 
width-needed the number of columns needed 

to display the menu, 
no-of -opt ions the number of options defined 

in the menu. 



menu-io 

the menu-object identifier (i.e.. it is the menu object "pointer".) (Output) It must not be 
altered in any way by the application program. 



ret-code 

return code. (Output) (See Appendix B.) 
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Entry: cb_jnenu__$delete 



Deletes a menu object from 



a given value segment 



USAGE 



declarations: 



77 
77 
77 
77 



di r-name 
entry-name 
name-of-menu 
ret-code 



PiC X(l68) . 
PIC X(32) . 
PIC X(32) . 



USAGE IS COMP-6. 



call "cb_menu_$delete" USING dir-name, entry-name, name-of-menu, 
ret-code. 

STRUCTURE ELEMENTS 



dir-name 

pathname of the directory containing the menu object. (Input) 
entry-name 

entry name of value segment containing the menu object. (Input) The suffix "value" need 
not be specified. 

name-of-menu 

name used to identify the menu object when the menu object was stored. (Input) 



return code. (Output) (See Appendix B.) 



Entry: cb menu_$describe 

Returns information about a menu object. It returns the number of options in the menu, the 
number of lines and number of columns required to display the menu. It is primarily used 
to determine if the menu can be displayed in a given window. 



ret-code 
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USAGE 

declarations: 

01 menu-needs USAGE IS COMP-6. 
02 1 i nes-needed. 
02 width-needed. 
02 no-of -opt ions. 

77 menu- id USAGE IS COMP-6. 
77 ret-code USAGE IS CONP-6. 

call "cb_menu_$descr ibe" USING menu- id, menu-needs, ret-code. 
STRUCTURE ELEMENTS 



menu-id 

the menu identifier returned by cb_menu_$create (or cb_menu_$retrieve in cases where 
the menu object has been stored). (Input) 

menu-needs 

a group item that contains menu related information on successful execution of call. 
(Output) 

Returned information: 

lines-needed the number of lines needed to 

display the menu, 
width-needed the number of columns needed 

to display the menu, 
no-of-option the number of options defined 

in the menu. 



ret-code 

return code. (Output) (See Appendix B.) 



Entry: cb ^menu__$destroy 

Used to free storage of a menu (not to be confused with cb_menu_$delete, which is used to 
delete the menu object from a value segment). Destroying the menu has no effect on the 
screen contents. 
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USAGE 

declarations: 

77 menu- id USAGE IS COMP-6. 
77 ret-code USAGE IS COMP-6. 

call "cb_menu__$destroy" USING menu-id, ret-code. 



STRUCTURE ELEMENTS 



menu-id 

menu identifier returned by cb_menu_$create or cb_menu_$retrieve. (Input/Output) (If 
usage-mode is 0 (see cb_menu_$init2) this operand will be ignored.) Set to an invalid 
value on return to prevent the old menu-id from being accidentally used. 

ret-code 

return code. (Output) (See Appendix R) 



Entry: cb menu ^(display 

Invoked to display a menu in a given window. 
USAGE 

declarations: 

77 window- id USAGE IS COMP-6. 
77 menu- id USAGE IS COMP-6. 

77 ret-code USAGE IS COMP-6. 

call "cb_menu_$di splay" USING window- id, menu- id, ret-code. 



STRUCTURE ELEMENTS 



window-id 

a window identifier returned by cb_window_$create entry point (Input) If usage-mode = 
0 this operand will be ignored (see cb_menu_$init2). 

menu-id 

menu identifier returned when the menu object was created or retrieved. (Input) 
ret-code 

return code. (Output) (See Appendix B.) 
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Entry: cb__menu__$get_choice 

Returns the choice made by the user, i.e., a number representing either the menu item chosen 
or the function key (or its equivalent escape sequence) entered. 

USAGE 

declarations: 



77 


f unct i on-key- i nf o 


PIC X(nl) 


• 




77 


window- id 


USAGE IS 


COMP- 


-6. 


77 


menu- id 


USAGE IS 


COMP- 


-6. 


77 


f keys 


USAGE IS 


COMP- 


-6. 


77 


selection 


USAGE IS 


COMP- 


-6. 


77 


ret-code 


USAGE IS 


COMP- 


-6. 



call "cb_menu__$get_choice" USING window-id, menu-id, funct i on-key- i nfo, 
fkeys, selection, ret-code. 

STRUCTURE ELEMENTS 



window-id 

a window identifier returned by the cb_window_$create entry point (Input) If 
usage-mode = 0 this operand will be ignored (see cb_menu_$init2). 

menu-id 

menu identifier returned by cb_menu_$create or cb_menu_$retrive. (Input) 
f unction-key-inf o 

a character elementary data item (nl as required) used to specify the role of function 
keys (if they exist for the terminal being used) or an equivalent set of escape sequences 
if the terminal does not have function keys or not the function keys required by the 
application. (Input) The objective is to let the application use the terminal's function 
keys if possible, else specify key sequences to be used to simulate function keys. Each 
character in the string corresponds to one function key. If the character is a space, then 
it is not relevant if the corresponding function key exists or not If the character is not 
a space, that character will be used to simulate a function key if the terminal does not 
have function keys. If the terminal does not have a function key for every non-space 
character in the string, then function keys will be simulated. Thus, the string " ?p q" 
means that the caller does not care whether the terminal has function key 0 or 3, but 
the caller does wish to use function keys 1,2, and 4. If any of these 3 function keys is 
not present on the terminal, then esc-? will substitute for Fl, esc-p will substitute for 
F2, and esc-q will substitute for F4. 

fkeys 

fkeys = 1 user entered a function key or escape sequence fkeys » 0 user selected an 
option (Output) 
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selection 

is a number representing the choice made by the liser. (Output) If the user has chosen 
an option, it is a number between 1 and the highest defined option. If the user has 
entered a function key, or escape sequence simulating a function key, it is the number 
associated with the function key. 

ret-code 

return code. (Output) (See Appendix B.) 
Entries: cb_menii ^Sinitl, cb ^menu ^$imt2 

These must be the first calls made to the menu manager. They set up the necessary 
environment for the menu application and return information concerning the user I/O 
window. 

USAGE 

declarations: 

inter code 
integer usage-mode 

call cb_menu_$ i n i t 1 

call cb_menu__$ i ni t2 (usage-mode, user-window-1 ines, user-window-columns, 
user-wi ndow- id, ret-code) 

STRUCTURE ELEMENTS 



usage-mode 

usage-mode = 0 means that the caller does not wish to do any explicit window 
management. (Input) When he/she wishes to display a menu, the window required will 
be automatically created. This means that the application will operate in a two window 
mode, the window containing the menu, and the user_io window. Both windows will be 
managed automatically for the user. If the user specifies this mode, all calls to the 
cb_window_ subroutine will be ignored and will return an appropriate error code. See 
Error Code Handling, below. All calls to the cb_menu_ subroutine that require a window 
identifier will ignore the user provided window-id. 

usage-mode = 1 means that the user wishes to define the number and characteristics of 
the windows to be used in the application. Thus, calls to cb_window_ will be supported 
and, for the entry points of cb_menu_ that require a window identifier, the caller must 
use a legal window-id (returned by cb_window_$create). 

user-window-lines 

the number of physical lines (rows) of the user i/o window when cb_menu_$init is 

called (which must be the first cb_menu_ call in the application.) Undefined if 
usage-mode « 0. (Output) 
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user-window-columns 

the number of colwnns of the user i/o window at time that cb_menu_$init is called (see 
immediately above). (Output) Undefined if usage-mode » 0. 

user-window-id 

window identifier of the user i/o window. (Output) Undefined if usage-mode » 0. 
ret-code 

return code. (Output) (See Appendix E) 



Entry: cb_menu ^$list 

Used to list the menu object(s), stored in value segment The menu objects selected are those 
that match the string input by the caller. 

USAGE 



declarations: 



01 matched-names. 

02 no-of-matches 
02 menu-names 



USAGE IS COMP-6. 
PIC X(32) OCCURS 



(ml) TIMES 



77 dir-name 

77 entry-name 

77 match-string 

77 ret-code 



PIC X(l68) . 
PIC X(32) . 
PIC X(32) . 
USAGE IS COMP-6 



call "cb_menu__$l i St" USING dir-name, entry-name, match-string, 
matched-names, ret-code. 



STRUCTURE ELEMENTS 



dir-name 

pathname of directory containing the menu object (Input) 
entry-name 

entry name of value segment containing the menu object (Input) The suffix "value" need 
not be specified. 

match-string 

a character elementary data item that is to be used as the selection criteria for 
determining what menu object, if any, is contained in the specified value segment that 
match (or contain) this string. (Input) 



no-of-matches 

the number of matches found. (Output) If none, then it is 0. 
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menu-names 

On return, contains the names of all menu objects, in the specified value segnent, that 
match the character string match-string. (Output) Note, if ml is not large enough to 
contain all the names, only ml names will be returned. 

ret-code 

return code. (Output) (See Appendix R) 



Entry: cb menu^Sretrieve 

Used to retrieve a menu object previously stored via the cb_menu_$store subroutine. 

USAGE 



declarations: 



77 dir-name PIC X (168) . 

77 entry-name PIC X (32) . 

77 name-of-menu. PIC X (32) . 

77 menu- id USAGE IS COMP-6. 

77 ret-code USAGE IS COMP-6. 

can "cb_menu__$retr ieve" USING dir-name, entry-name, name-of-menu, 
menu- id, ret-code. 



STRUCTURE ELEMENTS 



dir-name 

pathname of the directory containing the menu object, (Input) 
entry-name 

entry name of value segment containing menu object (Input) The suffix "value" need not 
be specified. 

name-of-menu 

name of the menu object used when the object was stored. (Input) 
menu-id 

is the menu id returned by the call. (Output) 
ret-code 

return code. (Output) (See Appendix B.) 
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Entry: cb ^meiiii^$store 

Used to store a menu object in a specified value segment 
USAGE 

declarations: 

77 dir-name PIC X (l68) . 

77 entry-name PIC X (32). 

77 name-of-menu PIC X (32) . 

77 create-seg USAGE IS COMP-6. 

77 menu- id USAGE IS COMP-6. 

77 ret-code USAGE IS COMP-6. 



call "cb__menu__$store" USING dir-name, entry-name, name-of-menu, 
create-seg, menu-id, ret-code. 

STRUCTURE ELEMENTS 



dir-name 

pathname of directory into which the menu object is to be placed. (Input) 
entry-name 

entry name of value segment into which menu object is to be placed. (Input) The suffix 
"value" need not be specified. 

name-of-menu 

is the name to be assigned to the stored menu object (Input) 
create-seg 

create-seg = 0 means do not store if value segment identified by en try -name does not 
already exist (Input) create-seg = 1 means create value segment, if it does not already 
exist and store menu object in it 

menu-id 

is the menu object identifier returned by cb_menu_$create or cb_menu_$retrieve. (Input) 
ret-code 

return code. (Output) (See Appendix E) 
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Entry: cb_menu ^$terminate 

Must be the last call to the menu manager in the menu application. 
USAGE 

declarations: none 

call "cb_menu_$termi nate". 

STRUCTURE ELEMENTS 
There are no arguments. 
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Name: cb__wiiidow_ 

This is the basic video interface subroutine to be used by CX)BOL to create/destroy/change 
windows. (If usage-mode = 0 (see cb_menu_$init2) this subroutine should not be called.) 

Its facilities are available through the following entry points. 
Entrjr: cb__wmdow__$chaiige 

This entry points provides a facility for changing the size of an existing window. The size of 
a window can always be "shrunk", however it can be increased only it does not overlap with 
another defined window. (If usage-mode = 0 (see cb_menu_$init2) this entry point should not 
be called.) 

USAGE 

decl arat ions: 

77 window- id USAGE IS COMP-6. 

77 first-line USAGE IS COMP-6. 

77 height USAGE IS COMP-6. 

77 ret-code USAGE IS COMP-6. 

call "cb_wi ndow_$change" USING window-id, first-line, height, 
ret-code. 



STRUCTURE ELEMENTS 



window-id 

window identifier returned by cb_window_$create. (Input) 

first-line 

new first line number for the window being changed. (Input) A positive value, 
height 

new height for the window being changed. (Input) A positive value, 
ret-code 

return code. (Output) (See Appendix B.) 
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Entry: cb__window__$clear__wmdow 
Used to clear a specified window. 
USAGE 

declarations: 

77 window- id USAGE IS COMP-6. 

77 ret-code USAGE IS COMP-6. 

call "cb_wi ndow_$ clear _wi ndow" USING window- id, ret-code. 
STRUCTURE ELEMENTS 



window-id 

the window identifier (returned by cb_window_$create) of the window to be cleared. 
(Input) 

ret-code 

return code. (Output) (See Appendix B.) 
Entry: cb__window ^(create 

This entry is used to create a new window on the terminal screen. (If usage-mode = 0 (s^ 
cb_menu_$init2) this entry point should not be called.) 

USAGE 

declarations: 

77 switch-name PIC X (32) . 
77 first- line USAGE IS COMP-6. 
77 height USAGE IS COMP-6. 

77 window- id USAGE IS COMP-6. 

77 ret-code USAGE IS COMP-6. 

call "cb_wi ndow_$ create" USING first- line, height, switch-name, 
window- id, ret-code. 

STRUCTURE ELEMENTS 



first-line 

is the line number where the window is to start (Input) 
height 

the number of lines used by the window, i.e., its height (Input) 
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switch-name 

the name that the caller wishes to associate with the switch. (Input) 
window-id 

the returned id of the window just created. (Output) It must not be altered in any way 
by the application program. 

ret-code 

return code. (Output) (See Appendix E) 



Entry: cb_window__$destroy 

Used to destroy a previously created window. (If usage-mode = 0 (see cb_menu_$init2) this 
entry point should not be called.) 

USAGE 

declarations: 

77 window- id USAGE IS COMP-6. 
77 ret-code USAGE IS COMP-6. 

call "cb_window_$destroy" USING window-id, ret-code. 



STRUCTURE ELEMENTS 



window-id 

window identifier (returned by the cb_window_$create). (Input/Output) It is reset to an 
illegal value by this call. 

ret-code 

return code. (Output) (See Appendix R) 
COBOL MENU APPLICATION EXAMPLES 

In the following two COBOL examples, a "Message" menu application is created that allows 
you to display, print, discard, or forward messages. Example 1 is a simple COBOL program 
that interfaces with the Multics menu manager via the cb_menu_ routine. Note in example 1 
that window management functions are called automatically through arguments in the 
ft_menu_$init2 subroutine. 

Example 2 is a COBOL program that interfaces with the Multics menu mans^er through the 
cb_menu_routine; in example 2, however, window management functions are performed by the 
cb_window_ routine. 
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EXAMPLE 1: 

In this example, all window management is done automatically. 

* A simple COBOL program interfacing with tlie Multics * 

* menu manager via the cb__menu_ routine. * 

CONTROL DIVISION. 

DEFAULT GENERATE AGGREGATE DESCRIPTORS. 
IDENTIFICATION DIVISION. 

PROGRAM- ID. 
cbtesti . 

AUTHOR. 

R. I . 

ENVIRONMENT DIVISION. 
CONFIGURATION SECTION. 
SOURCE-COMPUTER. 
Mul tics. 

OBJECT-COMPUTER. 
Mul tics. 

DATA DIVISION. 

WORKING-STORAGE SECTION. 

01 choices-table. 

02 choices PIC X(15) OCCURS 6 TIMES. 
01 headers-table. 

02 headers PIC X(ll*) OCCURS 1 TIMES. 
01 trailers-table. 
02 trailers PIC X(32) OCCURS 1 TIMES. 

01 keys-table. 
02 keys PIC X(l) OCCURS 6 TIMES. 

01 menu-format. 

02 menu-version USAGE IS COMP-6 VALUE 1. 

02 constraints USAGE IS COMP-6. 

03 max-width VALUE 79- 

03 max-height VALUE 10. 

02 no-of -columns USAGE IS COMP-6 VALUE 2. 
02 flags. 

03 center-headers PIC 9(1) VALUE 1. 

03 center- trailer PIC 9(1) VALUE 1. 



9-17 



CP51-02 



cb_wmdow. 



cb_window_ 



02 padder PIC X(l) VALUE 

01 menu-needs USAGE IS CONP-6. 
02 lines-needed. 
02 width-needed. 
02 no-of -opt ions. 



7 dir-name 


PIC X(l68) . 


/ entry nanie 


PIC X(32) 




7 menu-name 


PIC X(32) 




7 function-key- info 


PIC X(l) 


VALUE "q". 


7 me 


PIC X(7) 


VALUE "cbtestl". 


7 menu- id 








USAGE IS CONP- 


■6. 






7 ret-code 


USAGE 


IS 


COWP-6. 


7 window- id 


USAGE 


IS 


COMP-6. 


7 fkeys 


USAGE 


IS 


COMP-6. 


7 option 


USAGE 


IS 


COMP-6. 


7 easy-mode 


USAGE 


IS 


COMP-6 VALUE zero. 


7 user-wi ndow-1 1 nes 


USAGE 


IS 


COMP-6. 


7 user-window-columns 


USAGE 


IS 


COMP-6. 


7 usei — window- id 


USAGE 


IS 


COMP-6. 


7 create-seg 


USAGE 


IS 


COMP-6. 


7 keys-not-unique 


USAGE 


IS 


COMP-6. 


7 too-few-keys 


USAGE 


IS 


COMP-6. 


7 bad-arg 


USAGE 


IS 


COMP-6. 



PROCEDURE DIVISION. 

* The call to the cv_error_$name are used to collect the code for 
'< certain error messages that are of interest this application. 

Once these codes are retrieved the occurrence of that error can 

* be easily tested for. 

START- IT. 

CALL "cb_menu_$ini tl". 
CALL "cb_menu_$ i n i t2" USING easy-mode, user-wi ndow- 1 i nes, 
user-window-columns, user-wi ndow- id, ret-code. 

* The calls to cb_menu_$ i ni tl & 2 MUST be the first calls to cb_menu_. 

* They set up the appropriate environment for the menu application. 

IF ret-code EQUAL TO zero GO TO NEXT-ERR-CODE . 
CALL "com__err_" USING ret-code, me, "Internal error. 

Could not set up appropriate environment.". 
GO TO STOP- IT. 

CALL "cv_error_$name" USING "menu_et_$keys__not__unique" , 
keys-not-unique, ret-code. 
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call '•ioa_" USING "Error code for keys-not-unique - ^d", keys-not-unique. 

iF ret-code EQUAL TO zero GO TO NEXT-ERR-CODE . 

CALL "com__err_" USING ret-code, me, " (calling cv error_$name) ". 

GO TO STOP- IT. 

NEXT-ERR-CODE. 

CALL "cv_error $name" USING "error_table_$bad_arg", bad-arg, ret-code. 

IF ret-code EQUAL TO zero GO TO LAST-ERR-CODE . 

CALL "com_err_" USING ret-code, me , " (calling cv__error__$name) 

GO TO STOP- IT. 

LAST-ERR-CODE. 

CALL ••cv_error_$name" USING •'menu__et_$too_few_keys", too-few-keys, 
ret-code. 

IF ret-code EQUAL TO zero GO TO SET-UP. 

CALL "com_err_" USING ret-code, me, " (calling cv__error_$name) " . 
GO TO STOP- IT. 
SET-UP. 

MOVE 1 TO menu-version. 
MOVE "Display Message" TO choices(l). 
MOVE "Print Message" TO choices (2), 
MOVE "Discard Message" TO choices (3). 

MOVE "Forward Message" TO choices (4). 
MOVE "Reply Message" TO choices (5). 

MOVE "List Messages" TO choices (6). 
MOVE " MULT ICS MAIL " TO headers (1). 

MOVE "Press Fl or enter esc-q to quit" TO trailers (1). 
MOVE "1" TO keys(l) . 

MOVE "2" TO keys (2) . 
MOVE "3" TO keys (3) . 

MOVE "4" TO keys {k) . 
MOVE "5" TO keys (5) . 
MOVE "6" TO keys (6) . 



MENU-CREATE. 

DISPLAY choices-table. 
DISPLAY menu-version. 

CALL "cb_menu_$create" USING choices-table, headers-table, 

trailers-table, menu-format, keys-table, menu-needs, 
menu- id, ret-code. 

* This call creates a menu object and return the menu object 

* Identifier. This menu object is referenced as "menu- id". 
IF ret-code EQUAL TO zero GO TO STORE-MENU. 

CALL "com_err_" USING ret-code, me, " (calling cb_menu__$create) " . 
GO TO STOP- IT. 

STORE-MENU. 
MOVE ">udd>m>ri" TO dir-name. 
MOVE "menus_seg" TO entry-name. 
MOVE "cb_read__mai l_menu" TO menu-name. 
MOVE 1 TO create-seg. 
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CALL "cb_menu__$store" USING dir-name, entry-name, menu-name, 

create-seg, menu-id, ret-code. 
IF ret-code EQUAL TO zero GO TO DISPLAY-MENU. 
CALL "com_err " USING ret-code, me, "(calling cb__menu_$store) " . 
GO TO STOP-ItT 
DISPLAY-MENU. 

CALL "cb_menu__$di splay" USING window- id, menu- id, ret-code. 

* This call displays the menu in its own window at top of screen. 

* Since the usage-mode was set to 0, the program does not have to 

* create the window before calling cb_menu__$di splay. 

* The window- id argument is ignored. 

IF ret-code EQUAL TO zero GO TO GET-CHOICE. 

CALL "com_err__" USING ret-code, me, "Internal error. 

Menu could not be displayed." 
GO TO STOP- IT. 
GET-CHOICE. 

* Defines the function key requirements, i.e., 

* if the terminal has function key 1 (F1) then Fl will be used 

* to "quit", otherwise "esc q" will be used to "quit". 

CALL "cb_menu_$get_choice" USING window- id, menu- id, 

funct i on-key- i nfo, fkeys, option, ret-code. 
IF ret-code EQUAL TO zero GO TO TEST-FKEY. 

CALL "com_err_" USING ret-code, me, "Internal error. While getting 

user's choice.". 
GO TO STOP- IT. 

TEST-FKEY. 
IF fkeys EQUAL TO 1 

CALL "ioaj' USING "Exiting at your request." 
GO TO STOP- IT 
ELSE 

CALL "ioa " USING "You chose option '^d.", option 
GO TO GET-CHOICE. 

STOP- IT. 
CALL "cb_menu__$terminate" . 

* cb_menu_$ terminate MUST be the last call to cb_menu_ in the 

* application. It terminates the environment set up cb_menu_$ i n i t . 

EXIT PROGRAM. 
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EXAMPLE 2: 

In this example, COBOL interfaces with the Multics menu manager and the Multics window 
manner via the cb_menu_ and cb_window_ subroutines. 

^ A simple COBOL program interfacing with the Multics « 

* menu manager and window manager via the cb_menu_ and * 

* cb_window_ routines, respectively. * 

itit-kiiii'k'k'k'kitiiitiiiiii^itii-kii'kii-kit'k'kii^'kii'k'k-kii^'k'kliiiit'k^it'ki^itiiiiit^iiiiititli 

CONTROL DIVISION. 

DEFAULT GENERATE AGGREGATE DESCRIPTORS. 
IDENTIFICATION DIVISION. 

PROGRAM- ID. 
cbtest2. 

AUTHOR. 
R. I . 

ENVIRONMENT DIVISION. 

CONFIGURATION SECTION. 

SOURCE -COMPUTER. 
Mul t i cs . 

OBJECT-COMPUTER. 
Mul tics. 

DATA DIVISION. 
WORKING-STORAGE SECTION. 

01 choices-tablel . 

02choicesl PIC X (9) OCCURS 2 TIMES, 
01 choices-table2. 

02 choices2 PIC X(15) OCCURS 6 TIMES. 
01 choices-table3. 

02 choices3 PIC X(21) OCCURS 4 TIMES. 
01 headers-table. 

02 headers PIC X (23) OCCURS 1 TIMES. 
01 trailers-table. 
02 trailers PIC X (52) OCCURS 1 TIMES. 

01 keys-table. 
02 keys PIC X(l) OCCURS 6 TIMES. 

01 menu-format. 
02 menu-version USAGE IS COMP-6 VALUE 1. 
02 constraints USAGE IS COMP-6. 
03 max-width VALUE 80. 
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03 max-height VALUE 
02 no-of-columns USAGE 
02 flags. 

03 center -headers 

03 center- trai ler 
02 padder PI 

01 menu- need si 
02 1 i nes-neededl . 
02 width-neededl . 
02 no-of-optionsi . 

01 menu-needs2 
02 1 i nes-needed2. 
02 width-needed2. 
02 no-of-opt ions2. 

01 menu-needs3 USAGE 
02 1 i nes-needed3 • 

02 width-needed 3. 
02 no-of-opt ions3. 

77 dir-name 
77 entry-name 
77 menu-name 
77 function-key- info 
77 me 

77 switch-name 

77 1 ines-needed 
77 f ' rst-1 i ne 

77 height 
77 menu- id 
11 menu- idl 
77 menu-id2 
77 menu-id3 
77 ret-code 
77 curr-wi ndow-id 
77 window- id 
77 window- idl 
77 window-id2 
77 fkeys 
77 option 
77 do-it-yourself 
77 user-wi ndow-1 i nes 
77 user-window-columns 
77 user-wi ndow-id 
77 create-seg 

77 bad-window- id 



10. 

IS COMP-6 VALUE 2. 

PIC 9(1) VALUE 1. 
PIC 9(1) VALUE 1. 
C X(1) VALUE 

USAGE IS CONP-6. 



USAGE IS COMP-6. 



IS COMP-6. 



PIC X(168) . 
PIC X(32) . 
PIC X(32) . 

PIC X(2) VALUE "qf". 
PIC X(7) VALUE "cbtest2 



PIC X(32) 




USAGE 


IS 


COMP-6. 


USAGE 


IS 


COMP-6. 


USAGE 


IS 


COMP-6. 


USAGE 


IS 


COMP-6. 


USAGE 


IS 


COMP-6. 


USAGE 


IS 


COMP-6. 


USAGE 


IS 


COMP-6. 


USAGE 


IS 


COMP-6. 


USAGE 


iS 


COHP-6. 


USAGE 


IS 


COMP-6. 


USAGE 


IS 


COMP-6. 


USAGE 


IS 


COMP-6. 


USAGE 


IS 


COMP-6. 


USAGE 


IS 


COMP-6. 


USAGE 


IS 


COMP-6 VALUE 1 


USAGE 


IS 


COMP-6. 


USAGE 


IS 


COMP-6. 


USAGE 


IS 


COMP-6. 


USAGE 


IS 


COMP-6. 


USAGE 


IS 


COMP-6. 
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77 nonexistent-window USAGE IS COMP-6. 

77 insuff-room-for-window USAGE IS COMP-6. 

PROCEDURE DIVISION. 

* The call to the cv_error_$name are used to collect ^the code for 

* certain error messages that are of interest this application. 

* Once these codes are retrieved the occurrence of that error can 

* be easily tested for. 

START- IT. 

CALL "cv_error_$name" USING "video_et_$bad_wi ndow_id", 

bad-wi ndow-id, ret-code. 
IF ret-code EQUAL TO zero GO TO NEXT-ERR-CODE . 

CALL "com err_" USING ret-code, me, " (calling cv error__$name) " . 
GO TO STOP- IT. 

NEXT-ERR-CODE. 

CALL "cv_error_$name" USING "video_et_$nonexistent__window", 

nonexistent-window, ret-code. 
IF ret-code EQUAL TO zero GO TO LAST-ERR-CODE . 

CALL "com__err_" USING ret-code, me , " (calling cv_error_$name) " , 
GO TO STOP- IT. 

LAST-ERR-CODE. 

CALL "cv_error_$name" USING "video_et_$ insuf f_room_for__wi ndow" , 

insuff-room-for-window, ret-code. 
IF ret-code EQUAL TO zero GO TO SET-UP. 

CALL "com_err_" USING ret-code, me, " (calling cv_error__$name) ". 
GO TO STOP- IT. 
SET-UP. 

MOVE "Read Mail" TO choicesl (1) . 
MOVE "Send Mail" TO choicesl (2) . 

MOVE "Display Message" TO choices2(l). 

MOVE "Print Message" TO choices2(2). 
MOVE "Discard Message" TO choices2(3). 
MOVE "Forward Message" TO choices2 (^t) . 

MOVE "Reply Message" TO choices2(5). 

MOVE "List Messages" TO choices2(6). 

MOVE "Send New Message" TO choices3(l). 
MOVE "Send Deferred Message" TO choices3(2). 

MOVE "Print Sent Message" TO choices3(3). 

MOVE "Save Sent Message" TO choices3(^). 



MOVE "1" TO keys(l) . 

MOVE "2" TO keys (2) . 
MOVE "3" TO keys (3) . 

MOVE "i*" TO keys {k) . 
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MOVE "5" TO keys (5) . 
MOVE "6" TO keys (6) . 

CALL "cb^menu^Sini tl". 

CALL "cb_menu_$ i ni t2" USING do-it-yourself, user-wi ndow-1 ines, 
user-window-columns, user-wi ndow- id, ret-code. 

5'« The call to cb__menu_$ i n i 1 1 & 2 MUST be the first call to cb_menu_. 

* It sets up the appropriate environment for the menu application. 

* The application must do the window management, since 

* "do-i t-youself " is set to 1. 

IF ret-code EQUAL TO zero GO TO CREATE-F IRST-MENU. 
CALL "com_err_" USING ret-code, me, "Internal error. Could not set up 

appropriate environment.". 
GO TO STOP- IT. 

CREATE-F IRST-MENU. 

* Create first menu object. 

MOVE "Fl (or esc-q) = quit" TO trailers (1). 
MOVE "MULTICS MAIL" TO headers(l). 

CALL "cb_menu__$ create" USING choi ces-tabl el , headers-table, 

trailers-table, menu-format, keys-table, menu-needsl, 
menu-idl, ret-code. 

IF ret-code EQUAL TO zero GO TO CREATE-SECOND-MENU . 

CALL "com_err_" USING ret-code, me, " (calling cb_menu_$create) " . 

GO TO STOP- IT. 

CREATE-SECOND-MENU. 

* Create second menu object. 

MOVE "Fl (or esc-q) = quit; F2 (or esc-f) = first menu" TO trailers (1). 
MOVE "READ MAIL" TO headers(l). 

CALL "cb__menu_$ create" USING choi ces-tabl e2 , headers-table, 

trailers-table, menu-format, keys-table, menu-needs2, 
menu-id2, ret-code. 
IF ret-code EQUAL TO zero GO TO CREATE-TH I RD-MENU. 
CALL "com__err_" USING ret-code, me, " (calling cb__menu_$create) ". 
GO TO STOP- IT. 

CREATE-THIRD-MENU. 

* Create third menu object, 
MOVE "SEND MAIL" TO headers (1). 

CALL "cb_menu_$ create" USING choi ces-tabl e3, headers-table, 

trailers-table, menu-format, keys-table, menu-needs3* 
menu-id3« ret-code. 
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IF ret-code EQUAL TO zero GO TO STORE-MENU. 

CALL "com__err_" USING ret-code, me, " (calling cb_menu $create)". 
60 TO STOP- IT. 

STORE-MENU. 
MOVE ">udd>m>ri" TO dir-name. 
MOVE "menu__seg" TO entry-name. 
MOVE "cb_test_menu_" TO menu-name. 

MOVE 1 TO create-seg. 
CALL "cb_menu__$store" USING dir-name, entry-name, menu-name, 

create-seg, menu-idl, ret-code. 
IF ret-code EQUAL TO zero GO TO DISPLAY-IT. 

CALL "com__err_" USING ret-code, me, "(calling cb menu_$store) " . 
GO TO STOP- IT. 

DISPLAY-IT. 
MOVE -1 TO curr-wi ndow-id. 

* Setting curr-wi nd- id to "-1" means that there is no current window 

* def i ned . 

MOVE menu-idl TO menu- id. 

MOVE 1 i nes-neededl TO lines-needed. 

DISPLAY-FIRST-MENU. 

PERFORM CHANGE-MENU THRU GOBACK. 

* The user i/o window has been "shrunk", the window for the first menu 

* has been created, and the first menu has been displayed. 

MOVE window- id TO window-idl. 
IF ret-code EQUAL TO zero GO TO GET-IT. 
CALL "com_err_" USING ret-code, me, "Internal error. 

Menu could not be displayed." 
GO TO STOP- IT. 

GET-IT. 
PERFORM GET-CHOICE. 

* Get the user input. Two values are returned. (1) fkey. If fkey = 1, 

* then the user entered a function key (or its equivalent escape 

* sequence) . If fkey - 0 then the user has selected an option. (2) option. 

* If fkey = 1 then option is the function key number entered. (Fl = 1, 

* F2 = 2, etc.) . If fkey = 0, then option is the option number selected, 

* option - 1 means option 1 selected, etc. 

IF ret-code EQUAL TO zero GO TO TEST-FKEY. 

CALL "com_err__" USING ret-code, me, "Internal error. 

While getting user's choice.". 
GO TO STOP- IT. 

TEST-FKEY. 
IF fkeys EQUAL TO 1 

IF option EQUAL TO 1 
CALL "ioa " USING "Exiting at your request." 
GO TO STOP- IT 
ELSE 

GO TO GET- IT 
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ELSE 

IF option EQUAL TO 1 

MOVE menu-id2 TO menu- id 

MOVE 1 i nes-needed2 TO lines-needed 

PERFORM CHANGE-MENU THRU GOBACK 
ELSE 

MOVE menu-id3 TO menu- id 
MOVE 1 i nes-needed3 TO lines-needed 
PERFORM CHANGE-MENU THRU GOBACK. 
IF ret-code NOT EQUAL TO zero 
CALL "com_err_" USING ret-code, me, "Internal error. 

While trying to display menu." 
GO TO STOP- IT 
ELSE 

MOVE window- id TO window- id 2. 
NEXT-GET-IT. 
PERFORM GET-CHOICE. 

IF fkeys EQUAL TO zero GO TO CHOSE-OPTION. 
IF option EQUAL TO 1 

CALL "ioa_" USING "Exiting at your request." 

GO TO STOP- IT 
ELSE 

IF option GREATER 2 

GO TO NEXT-GET- IT 

ELSE 

MOVE menu-idl TO menu- id 

MOVE r ines-neededl TO lines-needed 

GO TO DISPLAY-FIRST-MENU. 

CHOSE-OPTION. 
CALL "ioa_" USING "You chose option '^d.", option. 
GO TO NEXT-GET- IT. 

GET-CHOICE. 

CALL "cb_menu_$get_choi ce" USING window-id, menu-id, 
function-key-info, fkeys, option, ret-code. 

CHANGE-MENU. 

* Destroy the current menu window. 
IF (cur r -window- id ) EQUAL TO -1 GO TO CHANGE-USER-WIND. 
CALL "cb window__$destroy" USING curr-wi ndow- id, ret-code. 

IF ret-code EQUAL TO zero GO TO CHANGE-USER-WIND. 
GO TO GOBACK. 

CHANGE-USER-WIND. 
COMPUTE first- line - lines-needed + 1. 
COMPUTE height « user -wi ndow- 1 i nes - lines-needed. 
CALL "cb_wi ndow_$change" USING user-window- id, first-line, height, 
ret-code. 

IF ret-code EQUAL TO zero GO TO CREATE-NEW-WI ND 
ELSE GO TO GOBACK. 
CREATE-NEW-WIND. 
MOVE "menu-window" TO switch-name. 
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MOVE 1 TO first- line. 
CALL "cb_wi ndow_$create" USING first- line, lines-needed, 

switch-name, window-id, ret-code. 
IF ret-code EQUAL TO zero GO TO DISPLAY-MENU 
ELSE 6^ T<^ e^A^K. 
DISPLAY-MENU. 

MOVE window- id TO curr-wi ndow-id. 
CALL "cb_menu_$di splay" USING window-id, menu-id, ret-code. 

CALL "cb_window_$clear_wi ndow" USING user-wi ndow-id, ret-code. 

GOBACK. 
EXIT. 

STOP- IT. 
CALL "cb_menu_$termi nate". 

* cb_menu__$termi nate MUST be the last call to cb_menu_ in the 

* application. It terminates the environment set up cb_menu_$ i n i t . 

EXIT PROGRAM. 
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APPENDIX A 
I/O SWITCH ATTACHMENTS 



This appendix reviews the standard I/O switch attachments, then describes how these 
attachments change when you activate the video system on your terminal and create a menu. 



There are four standard switches which are attached when your process is created. These 
switches are as follows: 

(1) user_i/o: this switch acts as a common collecting point for all terminal I/O. It's 
attached to your terminal through the I/O module tty_, and is opened for stream 
input and output 

(2) user.input: this switch controls command and data input at your terminal. It's 
attached to user_i/o through the I/O module syn_, and through that to your terminal. 
It's opened for stream inpuL 

(3) user_output: this switch controls command and data output at your terminal. It's 
attached to user_i/o through the I/O module syn_, and through that to your terminal. 
It's opened for stream output 

(4) erroT_output this switch controls output of error messages at your terminal. It's 
attached to user_i/o through the I/O module syn_, and through that to your terminal. 
It's opened for stream output 



To get information about I/O switch attachments, you can use the print_attach_table 
(pat) command. If you type "pat" on your terminal right after you log in, the systan will 
print the following: 

error_output syn__ user_i/o -inh close get_line get_chars 

user_input syn_ user__i/o -inh close put__chars 

user__i/o tty__ -logi n_channel 

stream__i nput_output 
user__output syn_ user_i/o -inh close get_line get_chars 
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You can see from this that user_input, user_output, and error_output are all attached 
via syn_ to iiser_i/o, which in turn is attached via tty_ to your terminal. Figure A-1 
illustrates these standard I/O switch attachments. 



When you activate the video system, by issuing a call to video_utils_$turn_on_login_channel 
or by executing the window_call invoke command, the existing tty_ attachment of your 
terminal is removed and replaced with video system attachments. The I/O switch user_i/o is 
now attached through the I/O module window_io_ to a new I/O switch, user_terminal_. 
User_terminaU is attached through the I/O module tc_io_ to your terminal. 
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If you type "pat" on your terminal after invoking video, the system will print the 
following: 



user_termi na]_ tc_io_ -logi n_channel 

stream_i nput_output 
error_output syn_ user_i/o -inh close get_line get_chars 

user^input syn__ user_i/o -inh close put__chars 

user_i/o window_io_ user_termi nal_ -first__line 1 -n_1ines 24 

stream_i nput__output Video 
user__output syn_ user_i/o -inh close get_line get_chars 



You can see from this that user_input, user_output, and error_output are still attached 
via syn_ to user_i/o, but that user_i/o is now attached via window_io_ to user_terminal_, 
which is in turn attached via tc_io_ to your terminal. User_i/o is now a window as well as 
a switch. It begins on line 1 of your screen and is 24 lines long. On a VIP7801 terminal, 
this means that the window covers the entire screen. Figure A-2 illustrates these changes to 
the standard I/O switch attachments. 



When you execute an exec_com to create a menu, the necessary attachments for your 
menu are built on top of those already set up by your activation of the video system. If 
you run the exec_com discussed in Section 3 (doc_sys.ec), then type "pat" on your terminal, 
the system will print the following: 

user_termi nal_ tc_io_ - 1 ogi n_channel 

stream__i nput_output 
error_output syn_ user_i/o -inh close get_line get_chars 

user_input syn_ user_i/o -inh close put_chars 

user__i/o window__io_ user__termi na 1__ -first_line 8 -n__lines 17 

stream_i nput__output Video 
user_output syn_ user_i/o -inh close get_line get_chars 

! BBBJLXDqDbHNnn.menu 

window_io__ user_termi na 1_ -first_1ine 1 -n__lines 7 

stream_input output Video 
8 n 007 1 khS^O . 6 1 3707 . exec_com 

ec__input__ ">udd>Project>Person>doc_sys.ec" stream_lnput 
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You can see from this that user_input, user_output, and error_output are still attached 
via syn_ to tiser_i/o, that user_i/o is still attached via window_io_ to user_terminal_, and 
that tiser_terminal_ is still attached via tc_ic_ to your terminal. But in addition, the 
!BBBjLXDqDbMNnn.menu is now attached through window_io_ to user_terminal_ also. (The 
unique character string "IBBBJLXDqDbMNnn" is generated by using the unique active function, 
as in the construction [unique] .menu, used in doc_sys.ec.) The user_i/o window still begins 
on line 1, but now it is only 7 lines long. The !BBBJLXDqDbMNnn.menu, which, like 
user_i/o, is a window as well as a switch, begins on line 8, and is 17 lines long. 



The last two lines printed above provide information about attachments made to 
support the execution of the exec_com. They are of no concern to you in this discussion. 
Figure A-3 illustrates I/O switch attachments after the video system has been activated and 
an exec_com creating a menu has been run. 



For more information on the print_attach_table command and the unique active | 
function, refer to the Multics Commands and Active Functions manual. Order No. AG92. | 
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APPENDIX B 



ERROR CODE HANDLING 



The subroutine cv_error_$name is provided in order to allow the FORTRAN and 
COBOL programmer to test return codes in a way similar to that provided by PL/I. 



It provides a means to associate an error "name", e.g., "menu_et_$too_few_keys" with 
the numeric value of the returned code. Once this is done the programmer can test for a 
given error code by using the name associated with it 

SYNTAX IN FORTRAN 

call cv_error_$name (error_name, converted_code, code) 
SYNTAX IN COBOL 

CALL "cv_error_$name" USING error-name, converted-code, ret-code. 

ARGUMENTS 

error_name (error-name) 

a quoted string, e.g., "menu_et_$too_many_options", which is name of the error. (Input) 

converted_string (converted-string) 

an integer (USAGE IS COMP-6 in COBOL) variable where the returned numeric value 
of the code is to be stored. (Output) 

code (FORTRAN) 

0 if call was successful, nonzero otherwise, (integer) (Output) 

ret-code (COBOL) 

0 if call was successful, nonzero otherwise. (USAGE IS COMP-6) (Output) 
NOTES 

"code" must be declared as "integer" in a FORTRAN program and "ret-code" as USAGE IS 
COMP-6 in a COBOL program. In every call, to any entry point defined in this document, 
a return code of zero always means that the call was executed successfully.) 
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Error codes of particular interest are: 

menu_et_$too_many_options 

(A menu can contain at most 61 choices.) 

menu_et_$too_f ew_keys 

(There are fewer keys than choices.) 

menu_et_$keys_noi_unique 

(Each key must be unique.) 

menu_et_$higher_than_max 

(The menu will not fit within the specified maximum height) 

video_et_$bad_window_id 

(The supplied window id was not valid.) 

video_et_$overlapping^windows 

(Two windows may not overlap on the screen.) 

video_et_$window_too_big (The screen is too small to accommodate a window of the 
requested size.) 

video_et_$insuf f _room_f OT_window 

(Insufficient room to create window.) 

video__et_$window_too_small 

(Tried to adjust window past minimum size.) 

video_et_$n^tive_screen„size 

(Native screen size specified.) 

video_et_$n^tive_window_size 

(Negative window size specified.) 

video_et_$nonexistent_window 

(Specified window does not exist) 

video_et_$overlaps_other_window 

(Specified window overlaps other windows.) 

video_et_$unable_to_create_window 
(Unable to create window.) 

video_et_$unable_to_dest_window 

(Unable to destroy window.) 

video_et_$switch_not_window 

(The specified switch is not attached as a window.) 

error_.table_$no_operation 

(Cannot call this entry point in your current mode. Requested operation could not be 
performed.) 
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INDEX 



MISCELLANEOUS 



k-5 
"E 4-5 

-Y J»-3 
# i»-5 



A 



arguments for window^call 
bell 5-n 

change_window 2-12, 5-12 
clear__region 5-12 
c 1 ear_to_end_of _l i ne 5-12 
clear_to the end of_window 
5-13 

c1ear_window 2-13» 5"13 
create_window 2-9. 5-13 



arguments for window_ca11 
(cont) 
delete_chars 5*1^ 
delete_window 2-12, 5-14 
get_echoed_chars 5" 14 
get__f i rst__ll ne 5" 15 
get__one_unechoed_char 5" 15 
get_position 5*15 
get_termi nal_height 5-16 
get__termi nal__width 5-16 
get_unechoed_chars 5" 16 
get_window_height 5-17 
insert text '^-IJ 
invoke 2-9, 5-17 
overwr i te_text 5" 18 
revoke 5" 18 
scrol l_region 5"18 
set_position 5" 19 
set_posi t lon_rel 5" 19 
supported_termi nal 5-19 
sync 5-19 
video_i nvoked 5-20 
wr 1 te_sync_read 5"20 

attaching video system 2-5 

attachments 
review of 

see also video attachments 
see standard attachments 
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COBOL interface 9"! 



backspace key k-2 

backward character 
"B h-k 

backward word 
ESC B it-5 

begi nni ng 1 i ne 
"A k-5 



C 



capitalize initial word 
ESC C lf-5 

capi tal ize word 
ESC U h-S 

cb_menu_ 9"2 

cb_menu__$create 9"2 
cb_menu__$de 1 ete 9~5 
cb_menu_$descr i be 9~5 
cb_nnenu_$destroy 9'"6 
cb_menu__$di splay 9~7 
cb_menu_$get_choi ce 9~8 
cb_menu__$ i n i 1 1 9~9 
cb_menu_$ i n i t2 9~9 
cb_menu_$l ist 9~10 
cb_menu_$retr i eve S-ll 
cb_menu_$ store 9" 12 
cb_menu_$termi nate 9" 13 

cb_window_ 9~l'f 

cb_wi ndow_$change 9" 14 
cb_w i ndow_$c 1 ear_wi ndow 
9-15 

cb__wi ndow_$ create 9-15 
cb_wi ndow_$destroy 9" 16 

clear and redisplay 
ESC h'k 

clear_window example 2-13 



control characters 
backward character 

^B !»-!» 
backward word 

ESC B k-5 
beginning 1 ine 

capitalize initial word 

ESC C k'5 
capital ize word 

ESC U k-5 
clear and redisplay 

ESC '"L k'k 
delete character 

k-5 
delete word 

ESC D k-5 
end of 1 i ne 

'^E k-5 
erase l»-2 

backspace key k-2 

DEL, # k-5 
erase word 

ESC DEL, ESC # k-5 
forward character 

"-F h-k 
forward word 

ESC F k-k 
kill k-2 
lower case word 

ESC L k-5 
quoting character 

-^Q k-k 
real-time editor 1»-1 
redisplay 

"L k-k 
retrieving deleted text 

ESC Y lf-3 

-Y 4-3 
twiddle word 

ESC T k-5 
two characters l»-2 

deleting words k-2 

retrieving deleted text 
4-3 

create_wi ndow example 2-10 
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D 



ESC DEL i*-5 



data structures 
menu_format 6-8 
menu_ \ i s t_ tirfo 6-5 
menu_requ! rements 6-11 

DEL l»-5 

delete character 
'"D k'5 

delete word 
ESC D 4-5 

de1ete_window example 2-12 

deleting words l»-2 

detaching video system 2-7 



end of 1 i ne 

end of window processing if- 10 

erase character k'2 
# lf-5 

backspace key k-2 
DEL if-5 

erase word 

ESC DEL, ESC # 4-5 

error_output switch A-1 

ESC # k'5 

ESC B l»-5 

ESC C k'5 

ESC D k-5 



ESC F k-k 

ESC L 4-5 

ESC T 4-5 

ESC U 4-5 

ESC Y 4-3 

examples 
exec__com 

attaching video 2^5 
clear_window 2-13 
create_wi ndow 2-10 
de1ete_wi ndow 2-12 
detaching video 2-7 
document system 3-2 
function keys 3-1 
function keys alternative 
3-1 

pll 

attaching video 2-6 
detaching video 2-7 
document system 3"6 
window_$clear_window 2-13 
wi ndow_$ create 2-il 
wi ndow_$destroy 2-12 

extens ions 

writing editor 4-5 



F 



forward character 
^F 4-4 

forward word 
ESC F 4-4 

ft_menu_ 8-2 

ft_menu_$ create 8-2 
f t_menu_$delete 8-4 
f t__menu_$descr ibe 8-4 
f t__menu_$destroy 8-5 
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ft_menu__ (cont) 

ft_menu_$di splay 8-6 
f t__menu_$get_choice 8"6 
f t_menu_$ i n i 1 1 8-8 
f t__menu_$ini t2 8-8 
f t__menu_$retr i eve 8-10 
ft_menu_$ store 8-10 
ft_menu_$ terminate 8-11 

ftjwindow__ 8-13 

ft__wi nclow__$ change 8-13 
f t_w i nclow_$c 1 ear_w i ndow 
8-11* 

ft__window_$ create ^-Ik 
f t__window__$destroy 8-15 

function keys 

alternatives 3-2 

guidel i nes for 3~1 

recommendations 3-2 

ttt info $f unction_key__data 

" 3-r 



I 



I/O modules 
tc_io_ 7-2 
window_io_ 7-5 



K 



kill character k-2 
kill ring i»-3 



L 



lower case word 
ESC L k-5 



menu 

definition 1-1 
games example 1-1 
managerial example l-i» 
manual orders example 1-3 
Multics tutorial example 
1-3 

programming example 1-5 

menu and video 

connection between 1-5 

menu commands 
menu_create 5-2 
menu_delete S'k 
menu_descr i be 5-5 
menu_di splay 5-6 
menu_get_cho i ce 5~7 
menu_l ist 5"9 

menu_ 6-2 

menu_$create 6-2 
menu_$de1ete 6*3 
menu_$descr ibe 6"i» 
menu_$destroy 6-^* 
menu_$di splay 6-5 
menu_$get_choice 6-5 
menu__$list 6-6 
menu_$retr i eve 6*7 
menu__$store 6-8 

menu_create command 5-2 

menu_de1ete command S~k 

menu^descr i be command 5~5 

menu_di splay command 5~6 

menu_format data structure 
6-8 

menu_get_choice command 5-7 
menu^list command 5-9 
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menu_1 i st_i nfo data structure 
6-9 

menu__requi rements data 
structure 6"11 

miscellaneous capabilities 
in windows 2-k 

MORE processing if-1, J*- 10 



0 



operations 

on windows 2-8 

change_wi ndow 2-12 
clear__window 2-13 
create_wi ndow 2-9 
set_wi ndow_i nf o 2-12 

output buffering If- 11 

output control i»-l 

overlap rule for windows 2-8 



P 



positioning tiie cursor 
in windows 2-3 

pr int_attach__table description 
see the Commands manual 



Q 



quoting character 



R 



real-time editor i»-l 
control characters lf-1 
deleting words 4-2 
erase and Icill values i|-l 
erase character if-2 
Icill character i»-2 
retrieving deleted text 4-3 

red i splay 

requirements for windows 2-8 

retrieving deleted text l»-3 
ESC Y i|-3 
'^Y 4-3 

rout i nes 

1 ine editor 4-6 



S 



scrol 1 ing 

in windows 2-4 

selective alteration 
in windows 2-4 

selective erasure 
in windows 2-4 

standard attachments A-1 
after invoking video A-4 
i 1 lustration of A-3 
via syn_ A-2 
via tty_ A-2 

standard I/O switch A-1 

standard I/O switch 
attachments 
see also standard 
attachments 
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standard switch names 
error_output A-1 
user_input A-1 
user_io switch A-1 
user_output A-1 

switch attachments 

see also video attachments 
see standard attachments 

syn_ 

see the Subroutines manual 



T 



tc_io_ 7-2 

attach description 7~2 

control operations 
clear_screen 7"3 
get_break__table 7"3 
get_capab i 1 i t i es 7 " 3 
reconnect ion 7"4 
set_brealc_table 7~3 
set_l i ne__speed 7"3 
set_term_type 7"4 

get line operation 7~3 

open operation 7''3 

trai ler 1 i nes 2-8 
tty_ 

see the Subroutines manual 

twiddle word 
ESC T i*-5 



U 



unique active function 
see the Commands manual 

user_input switch A-1 

user io switch A-1 



user_io window 2-5, 2-9, 2-12, 
2-13. 3-2 
size of 2-5 

user_output switch A-1 

uti 1 i ties 

window editor i(-8 



V 



video and menu 

connection between 1-5 

video attachments A-2 
after exec_com execution 
A-1* 

i 1 lustration of A-6 

tc__io_ A-l» 

via window_io_ A-J* 

video command 

window_can 5-10 

video subroutines 
video__data__ 6-12 
V i deo_da ta_$ term i na 1 _ i ocb 
6-12 

video__ut i 1s_ 6*13 
video__uti ls_$ 

turn_of f_login channel 

turn_on__login channel 2-9* 
6-13 
window_ 6-15 
w i ndow_$ 

c 1 ear_to_end__of __wi ndow 
6-18 

get__one_unechoed char 
6-21* 

window_$be11 6"15 
window_$change__co1umn 6-16 
wi ndow_$change__l i ne 6-16 
wi ndow_$clear_region 6-17 
wi ndow_$c]ear_to_end_of_l i ne 
6-18 

window_$clear__window 6-19 
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video subroutines (cont) 

w i ndow_$c 1 ear_w i ndow ex amp 1 e 

2-13 

window_$create 6~19 
wi ndow_$ create example 2-11 
w i mi bw_$de T e t e~c h a r s 6-2 0 
wi ndow_$destroy 6~21 
window__$destroy example 
2-12 

wlndow_$edi t_] ine 6~21 
wi ndow_$get__cursor_posi t ion 
6-22 

window_$get echoed_chars 
6-23 

window $get uneclioed_chars 
6-25 

window__$insert__text 6-26 
W! ndow__$overwri te_text 6"26 
wi ndow_$pos 1 1 1 on_cursor 
6-27 

wi ndow_$posi tion_cursor rel 
6-27 

wi ndow_$scrol l__region 6-28 

wtndow_$sync 6-29 

wi ndow_$wr i te_raw__text 6-29 

video system 
attaching 2-5 
command interface 1»-11 
detaching 2-7 
features 4-1 

end of window processing 
ii-10 

MORE processing lf-1. If- 10 
output control lf-1 
real-time editing 4-1 
windows 2-1 
subroutine interface 4-11 



W 



wi ndow 

w i ndow__ed i tor_ut i 1 s__$ 
backward 4-9 
backward_word 4*9 
delete_text 4-8 
delete_text__save 4-9 



window (cont) 

w i ndow_ed i tor_u t i 1 s__$ 

get top_k ill r i ng__e i emen t 
" 4-9 

i nser tjtext 4--8- - - 

move_backward word 4"9 
move_forward 4-9 
move_forward word 4"9 
rotate_ki I luring 4- 10 

w i ndows 

definition 2-1 
height of 2-9 
miscellaneous capabilities 

2-4 

naming of 2-9 
number permitted 2-8 
operations 2-1, 2-8 

change_wi ndow 2-12 

clear_window 2-13 

create_wi ndow 2-9 

set__wi ndow_i nfo 2-12 
overlap rule 2-8 
positioning cursor 2-3 
requirements 2-8 
scrolling 2-4 
selective alteration 2-4 
selective erasure 2-4 
trailer lines 2-8 
width of 2-8 

window^ 4-11* 6-15 
wi ndow_$ 

c 1 ear_to_end_of _w i ndow 
6-18 

get_one_unechoed_char 
6-24 

wi ndow__$bel 1 6-15 
wi ndow_$change_column 6" 16 
wi ndow_$change_l i ne 6-16 
wi ndow_$clear_region 6-17 
wi ndow_$c I ear__to_end_of __1 1 ne 
6-18 

window_$clear_window 6-19 

example 2-13 
wi ndow_$ create 6-19 

example 2-11 
wi ndow_$del ete_chars 6-20 
wi ndow_$destroy 6-21 
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window_ (cont) 
w i ndow_$des t r oy 
example 2-12 
wi ndow_$ed i t__l i ne 6"2 1 
window $get cursor position 
6-22 

window_$get echoed chars 
6-23 

wi ndow__$get_unechoed chars 
6-25 

window_$insert_text 6-26 
window__$overwri te_text 6-26 
wi ndow_$pos i t i on_cursor 
6-27 

window $position_cursor_rel 
6-27 

window_$scrol l__region 6-28 
window_$sync 6-29 
w i ndow__$wr i te_r aw_tex t 6-29 
wi ndow__$wr i te_sync read 
6-30 

window_ca1t 

window_call arguments 
see arguments for 
w i ndow__ca 1 1 

window_ca11 command 5-10 

window__io_ 7-5 

attach description 7-5 

control operations 
get_break_table 7-15 
get_capabi 1 i ti es 7-9 
get_edi ting_chars 7-10 
get_more__responses 7-11 
get output conversion 

■* 7-16 
get_special 7-16 
get__tolcen_characters 7-20 
get_window__info 7-7 
get_wi ndow_status 7-8 
reset__more 7-10 
set__break__table 7-15 
set__edi ting_chars 7-10 
set_more__responses 7-11 
set_output__convers ion 
7-16 



w i ndow__ i o_ (cont) 
control operations 

set_specia1 7-17 

set_token_characters 7"20 

set_window__inf o 7-7 

set_window__status 7-8 
control operations from 
command level 7-26 
get chars operation 7-6 
get line operation 7"6 
modes operations 

can, ^can 7-25 

ctl char, ^ctl__char 7-25 

erkl, ^erkl 7*25 

esc, ^esc 7-26 

n 7-26 

more, ^ore 7-21* 
more__mode 7-2if 
pl 7-26 

rawi, '^rawi 7-26 

rawo, '^rawo 7-25 

red, -^red 7-26 

vertsp, 'Vertsp 7-25 
open operation 7-6 
put chars operation 7-6 



i-8 



CP51-02 



HONEYWELL INFORMATION SYSTEMS 
Technical Publications Remarks Form 



TITLE 



MULTICS MENU CREATION FACILITIES 



ORDER NO. 



DATED 



CPS 1-02 



FEBRUARY 1985 



ERRORS IN PUBLICATION 



SUGGESTIONS FOR IMPROVEMENT TO PUBLICATION 



|-Ky Your comments will be investigated by appropriate technical personnel 
I y and action will be taken as required. Receipt of all forms will be . — . 
acknowledged; however, if you require a detailed reply, check here. LJ 



FROM: NAME : DATE 

TITLE 

COMPANY 



ADDRESS 



PLEASE FOLD AND TAPE- 
NOTE: U. S. Postal Service will not deliver stapled forms 



NO POSTAGE 
NECESSARY 
IF MAILED 
IN THE 
UNITED STATES 



BUSINESS REPLY MAIL 

FIRST CLASS PERMIT NO. 39531 WALTHAM, MA02154 



POSTAGE WILL BE PAID BY ADDRESSEE 



HONEYWELL INFORMATION SYSTEMS 
200 SMITH STREET 
WALTHAM, MA 02154 



ATTN: PUBLICATIONS, MS486 



Honeywell 



Together, we can find the answers. 



Honeywell 

Honeywell information Systems 

U.S.A.: 200 Smith St., MS 486, Waltham, MA 02154 
Canada: 155 Gordon Baker Rd., Willowdale, ON M2H 3N7 
U.K.: Great West Rd., Brentford, Middlesex TW8 9DH Italy: 32 Via Pirelli, 20124 Milano 
Mexico: Avenlda Nuevo Leon 250, Mexico 11 , D.F. Japan: 2-2 Kanda Jimbo-cho, Chiyoda-ku, Tokyo 
Australia: 124WalkerSt.,NorthSydney, N.S.W. 2060 S.E.Asia: Mandarin Plaza, Tsimshatsui East, H.K. 



42356, 7.5C385, Printed in U.S.A. 



CP51-02 



